DOCSEARCHbyAlgolia
Submit Docs

Kubefirst Documentation

repository·main·Indexed 24 days ago

https://github.com/konstructio/kubefirst

A Cluster Management Platform for application delivery that provides a CLI to bootstrap GitOps-ready platforms. It supports multiple cloud providers including AWS, Azure, GCP, Akamai, Civo, DigitalOcean, Vultr, and local environments like k3d and K3s. The CLI automates the creation of management and workload clusters, GitOps repositories, and DNS configurations, integrating cloud-native tools such as ArgoCD, Kbot, and Vault.

Tokens
14.6K
Snippets
7
Records
85
Agent score
84%

What's inside Kubefirst

  2. Install Kubefirst CLI on various cloud platforms

    main

    The Kubefirst CLI is used to create instant GitOps platforms by integrating cloud-native tools. Installation processes, prerequisites, and resulting platform configurations vary depending on your target environment.

    Detailed installation guides are available for the following providers:

    • Akamai
    • AWS
    • Azure
    • Civo
    • DigitalOcean
    • Google Cloud
    • Vultr
    • K3s
    • k3d (for local development)

  3. Report issues and ask questions about Kubefirst

    main

    If you encounter problems or have questions regarding Kubefirst, use the following channels:

    • General Questions: Join the Kubefirst Slack community and ask in the #helping-hands channel. For private inquiries, you can direct message the Principal Developer Advocate, Frédéric Harper (@Fred) on Slack.
    • Bug Reports: If you have identified a definitive bug in the platform, create an issue on the GitHub issues page.

  4. Kubefirst CLI execution and logging behavior

    main

    The Kubefirst CLI manages its own configuration and logging lifecycle upon startup.

    Configuration and Paths

    • The CLI reads configuration using configs.ReadConfig().
    • It uses viper for configuration management.
    • It maintains a local directory at ~/.k1 for its operational data.
    • It automatically creates a logs subdirectory within ~/.k1.

    Logging Mechanism

    • Log Directory: ~/.k1/logs
    • Log File Naming:
      • For create commands: The log file is named log_<cluster-name>.log. If the --cluster-name flag is provided, that name is used; otherwise, the Unix epoch is used.
      • For logs commands: The CLI reuses the existing log file name stored in the configuration under k1-paths.log-file-name.
      • For other commands: A new log file is created using the current Unix epoch: log_<epoch>.log.
    • Logging Formats:
      • The CLI uses both the standard Go log package (prefixed with LOG: ) and zerolog for structured logging. Both are directed to the session log file.

    Terminal UI

    • If the command includes k3d in its arguments, the CLI initializes a progress terminal using the progress package to provide interactive feedback during execution.

  5. Understand the k3d cluster creation lifecycle

    main

    When running the k3d create command, Kubefirst performs a multi-stage automated setup to transition from a raw K3D cluster to a fully configured platform. The lifecycle includes:

    1. Minio Setup: Uploading necessary objects to a Minio bucket.
    2. Vault Configuration: Port-forwarding to the Vault instance, retrieving the root token from a Kubernetes secret (vault-unseal-secret), and executing Terraform to configure Vault.
    3. User Provisioning: Executing Terraform to create users based on the configured Git provider.
    4. GitOps Repository Detokenization: Preparing the GitOps repository by renaming backend files (e.g., remote-backend.md to remote-backend.tf) and committing/pushing the initial content.
    5. Deployment Verification: Waiting for Argo Workflows and the Kubefirst deployment to reach a ready state.
    6. Finalization: Exporting cluster metadata, opening the Kubefirst console in the local browser, and displaying a handoff screen.

  6. Manage k3d local installations with the kubefirst CLI

    main
    The k3d command (and its alias local) allows you to manage a local Kubefirst platform installation using k3d. You can use these commands to provision a new cluster, destroy existing resources, manage SSL certificates, retrieve platform credentials, or unseal Vault.

  7. Configure k3d cluster creation via Kubefirst CLI

    main

    The k3d command in the Kubefirst CLI automates the creation of a local Kubernetes cluster using k3d, sets up GitOps repositories (GitHub or GitLab), configures cloud infrastructure via Terraform, and bootstraps essential services like Argo CD, Vault, and Minio.

    Prerequisites

    • Git Provider Token: You must provide a token for your chosen Git provider via environment variables:
      • GitHub: GITHUB_TOKEN
      • GitLab: GITLAB_TOKEN (also requires the --gitlab-group flag).
    • Disk Space: A minimum of 10 GB of available disk space is required.
    • SSH Configuration: If using GitHub or GitLab, ensure the host is in your ~/.ssh/known_hosts file (e.g., ssh-keyscan github.com >> ~/.ssh/known_hosts).

    Key Configuration Options

    • Git Provider: Choose between github or gitlab using the --git-provider flag.
    • Git Protocol: Specify https or ssh using the --git-protocol flag.
    • Cluster Name: Define the cluster name with --cluster-name.
    • GitOps Template: Override the default GitOps template using --gitops-template-url and --gitops-template-branch.
    • Catalog Apps: Use --install-catalog-apps to include specific applications from the catalog.
    • Telemetry: Enable or disable telemetry using --use-telemetry.

  8. Destroy a k3d-based Kubefirst platform

    main

    Use the destroy command within the k3d context to tear down a Kubefirst platform running in a k3d cluster. This process performs several cleanup tasks:

    1. Preflight Checks: Ensures port 9000 is available for port-forwarding to MinIO (required for Terraform destruction).
    2. Git Provider Cleanup: If configured, uses Terraform to destroy resources in GitHub or GitLab (e.g., webhooks, repositories).
    3. GitLab Specifics: For GitLab providers, it attempts to delete container registry repositories for gitops and metaphor projects and removes managed SSH keys if a title is provided.
    4. k3d Cluster Destruction: Deletes the k3d cluster itself.
    5. Local Cleanup: Resets the $HOME/.kubefirst configuration and removes the local Kubefirst directory (K1DIR).

    Requirements:

    • You must have a valid Git token set via environment variables (GITHUB_TOKEN or GITLAB_TOKEN).
    • Port 9000 must not be in use by any existing port-forwards.

  9. Configure environment variables for Vultr creation

    main

    Before running Vultr creation commands, you must ensure the following environment variables are set:

    • VULTR_API_KEY: Required for all Vultr operations.
    • CF_API_TOKEN: Required only if using cloudflare as the DNS provider.

    If these are missing, the command will fail with an error indicating the variable is unset.

  10. Configure Google Cloud credentials for Kubefirst

    main

    To use Google Cloud platform creation commands in the Kubefirst CLI, you must provide Google Application Credentials via the GOOGLE_APPLICATION_CREDENTIALS environment variable. This variable should point to a valid service account key file.

    If the environment variable is not set or the file cannot be opened, the command will fail.

  11. Use the kubefirst CLI

    main

    The kubefirst command is a management cluster installer used to provision an open source application delivery platform. The CLI is organized into subcommands categorized by cloud provider or specific management tasks.

    To see all available commands and their descriptions, run:

    kubefirst help

  12. Authenticate Azure with Kubefirst using Service Principal environment variables

    main

    To use Azure platform creation commands, you must authenticate using an Azure Service Principal. Kubefirst requires the following environment variables to be set in your shell session:

    • ARM_CLIENT_ID: The Client ID of your Service Principal.
    • ARM_CLIENT_SECRET: The Client Secret of your Service Principal.
    • ARM_TENANT_ID: The Tenant ID of your Azure AD tenant.
    • ARM_SUBSCRIPTION_ID: The Subscription ID where resources will be created.

    Refer to the Azure Service Principal documentation for instructions on how to create these credentials.