This guide will cover the onboarding process for a private repository using Flux’s GitHub bootstrap. The flux2-multi-tenancy project is used as an example to demonstrate the process.
Prerequisites
- Familiarity with Kubernetes, Git, and Helm
- A GitHub account and a repository for your project
- Flux installed in your cluster
Flux GitHub Bootstrap
Flux can be bootstrapped to connect to a GitHub repository using the flux bootstrap github command. This command creates the GitHub repository if it doesn’t exist and commits the Flux manifests to the specified branch. It then configures the target cluster to synchronize with that repository.
Here’s an example of how to use the flux bootstrap github command:
flux bootstrap github \
--owner=<organization> \
--repository=<repository name> \
--branch=main \
--path=clusters/my-cluster
Replace <organization> and <repository name> with your GitHub organization and repository name. The --branch flag specifies the branch where Flux will commit the manifests, and the --path flag specifies the path to the Flux configuration files in the repository.
If the Flux components are present on the cluster, the bootstrap command will perform an upgrade if needed.
GitHub Personal Access Token
When using --token-auth, the CLI and the Flux controllers running on the cluster will use the GitHub PAT to access the Git repository over HTTPS. The GitHub PAT is stored in the cluster as a Kubernetes Secret named flux-system inside the flux-system namespace.
To avoid storing your PAT in the cluster, you can configure GitHub Deploy Keys instead.
GitHub Organization
If you want to bootstrap Flux for a repository owned by an GitHub organization, it is recommended to create a dedicated user for Flux under your organization. Generate a GitHub PAT for the Flux user that can create repositories by checking all permissions under repo. If you want to use an existing repository, the Flux user must have admin permissions for that repository.
Run the bootstrap for a repository owned by a GitHub organization:
flux bootstrap github \
--token-auth \
--owner = my-github-organization \
--repository = my-repository \
--branch = main \
--path = clusters/my-cluster
Assigning Organization Teams
You can specify a list of GitHub teams with --team=team1-slug,team2-slug, those teams will be granted maintainer access to the repository.
flux bootstrap github \
--token-auth \
--owner = my-github-organization \
--repository = my-repository \
--branch = main \
--path = clusters/my-cluster \
--team=team1-slug,team2-slug
GitHub Enterprise
To run the bootstrap for a repository hosted on GitHub Enterprise, you have to specify your GitHub hostname:
flux bootstrap github \
--token-auth \
--hostname=<github-hostname>
Flux Multi-Tenancy
Flux supports segmentation and isolation of resources by using namespaces and role-based access control (RBAC). Flux defers to Kubernetes’ native RBAC to specify which operations are authorized when processing its custom resources.
To create a tenant with access to a namespace, use the flux create tenant command:
flux create tenant dev-team \
--with-namespace=frontend \
--label=environment=dev
This command generates namespaces, service accounts, and role bindings to limit the reconcilers’ scope to the tenant namespaces.
Security
For more information on securing Flux deployments, refer to the Flux Security documentation.
