{"id":48229103,"url":"https://github.com/controlplaneio-fluxcd/d2-fleet","last_synced_at":"2026-04-04T19:29:15.968Z","repository":{"id":280000869,"uuid":"940627702","full_name":"controlplaneio-fluxcd/d2-fleet","owner":"controlplaneio-fluxcd","description":"Example repository for cluster fleet management with Flux Operator and Gitless GitOps","archived":false,"fork":false,"pushed_at":"2025-10-06T13:14:17.000Z","size":69,"stargazers_count":8,"open_issues_count":2,"forks_count":6,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-10-06T15:14:16.178Z","etag":null,"topics":["fluxcd","gitops"],"latest_commit_sha":null,"homepage":"https://fluxcd.control-plane.io/","language":"HCL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/controlplaneio-fluxcd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-02-28T14:09:19.000Z","updated_at":"2025-10-06T13:14:19.000Z","dependencies_parsed_at":"2025-02-28T21:27:06.302Z","dependency_job_id":"c698b90f-5eca-45a1-8616-416e1c6cd62a","html_url":"https://github.com/controlplaneio-fluxcd/d2-fleet","commit_stats":null,"previous_names":["controlplaneio-fluxcd/d2-fleet"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/controlplaneio-fluxcd/d2-fleet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/controlplaneio-fluxcd%2Fd2-fleet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/controlplaneio-fluxcd%2Fd2-fleet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/controlplaneio-fluxcd%2Fd2-fleet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/controlplaneio-fluxcd%2Fd2-fleet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/controlplaneio-fluxcd","download_url":"https://codeload.github.com/controlplaneio-fluxcd/d2-fleet/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/controlplaneio-fluxcd%2Fd2-fleet/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31410681,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fluxcd","gitops"],"created_at":"2026-04-04T19:29:15.330Z","updated_at":"2026-04-04T19:29:15.956Z","avatar_url":"https://github.com/controlplaneio-fluxcd.png","language":"HCL","funding_links":[],"categories":[],"sub_categories":[],"readme":"# d2-fleet\n\n\u003e [!NOTE]\n\u003e This repository is part of the reference architecture for the\n\u003e [ControlPlane Enterprise for Flux CD](https://fluxcd.control-plane.io/).\n\u003e\n\u003e The `d2` reference architecture comprised of\n\u003e [d2-fleet](https://github.com/controlplaneio-fluxcd/d2-fleet),\n\u003e [d2-infra](https://github.com/controlplaneio-fluxcd/d2-infra) and\n\u003e [d2-apps](https://github.com/controlplaneio-fluxcd/d2-apps)\n\u003e is a set of best practices and production-ready examples for using Flux Operator\n\u003e and OCI Artifacts to manage the continuous delivery of Kubernetes infrastructure and\n\u003e applications on multi-cluster multi-tenant environments.\n\u003e \n\u003e Download the guide: [Flux D2 Architectural Reference](https://raw.githubusercontent.com/controlplaneio-fluxcd/distribution/main/guides/ControlPlane_Flux_D2_Reference_Architecture_Guide.pdf)\n\n## Scope and Access Control\n\nThis repository is managed by the platform team who are responsible for\nthe Kubernetes infrastructure and have direct access to the fleet of clusters.\n\nThe platform team that manages this repository must have **admin** rights to the `d2-fleet` repository\nand **cluster admin** rights to all clusters in the fleet to be able to perform the following tasks:\n\n- Bootstrap Flux Operator with multi-tenancy restrictions on the fleet of clusters.\n- Configure the delivery of platform components (defined in [d2-infra repository](https://github.com/controlplaneio-fluxcd/d2-infra)).\n- Configure the delivery of applications (defined in [d2-apps repository](https://github.com/controlplaneio-fluxcd/d2-apps)).\n\n## OCI Artifacts\n\nThe content of the D2 repositories are packaged as OCI Artifacts and published\nto GitHub Container Registry using GitHub Actions workflows defined in each repository.\nThe artifacts are signed with the Cosign keyless procedure using the GitHub Actions OIDC.\n\nFlux running in the clusters, pulls the OCI Artifacts to reconcile the desired state and\nverifies the integrity of the content using the Cosign signature. On production clusters,\nthe artifacts signature subject must match the GitHub repository, Git tag and the\nGitHub workflow used to publish the artifact.\n\n### Fleet Artifacts\n\nThe artifacts published to `oci://ghcr.io/controlplaneio-fluxcd/d2-fleet` are tagged as:\n\n- `main-\u003ccommit-short-sha\u003e` for the main branch commits.\n- `latest` points to the latest artifact tagged as `main-\u003ccommit-short-sha\u003e`.\n- `vX.Y.Z` for the release tags.\n- `latest-stable` points to the latest artifact tagged as `vX.Y.Z`.\n\nThe Flux Operator running on the Kubernetes clusters in the fleet is configured with a\n[FluxInstance](https://github.com/controlplaneio-fluxcd/d2-fleet/blob/main/clusters/staging/flux-system/flux-instance.yaml)\npointing to the OCI Artifact that defines the desired state of each cluster. The staging clusters\nare synced from the `latest` tag, while the production clusters are synced from the `latest-stable` tag.\n\n### Components Artifacts\n\nThe infrastructure components from `d2-infra` and the applications from `d2-apps` follow the same pattern\nand are packaged as OCI Artifacts. The delivery of these components is performed by the Flux Operator\nusing the [ResourceSet](https://github.com/controlplaneio-fluxcd/d2-fleet/tree/main/tenants) definitions.\n\nEach component is published to a dedicated OCI repository, for example, the `frontend` component\nis published to `oci://ghcr.io/controlplaneio-fluxcd/d2-apps/frontend` and is tagged as:\n\n- `latest` for the main branch commits that modify the component.\n- `vX.Y.Z` for the release tags matching the Git tag format `\u003ccomponent\u003e/vX.Y.Z`.\n- `latest-stable` points to the latest artifact tagged as `vX.Y.Z`.\n\nA component artifact contains the Kubernetes manifests (Flux resources and Kustomize overlays)\nthat define the desired state of the component for the whole fleet of clusters:\n\n```text\n.\n├── base\n│   ├── kustomization.yaml\n│   └── helm-release.yaml\n├── production\n│   ├── kustomization.yaml\n│   └── values-patch.yaml\n└── staging\n    ├── kustomization.yaml\n    └── values-patch.yaml\n```\n\nWhen Flux Operator reconciles the `ResourceSet` for the components, it configures the components tagged\nas `latest` to be deployed on the staging clusters, and the ones tagged as\n`latest-stable` to be deployed in production.\n\nRolling back a component in production can be done by moving its `latest-stable` tag to a previous version,\nfor example, `flux tag oci://ghcr.io/controlplaneio-fluxcd/d2-apps/frontend:v1.2.3 --tag latest-stable`.\n\nThe semver tags are considered immutable, while the `latest-stable` tag act as a pointer to the\nlatest release of the component.\n\n## Bootstrap Procedure\n\nThe bootstrap procedure is a one-time operation that installs the Flux Operator on the cluster,\nconfigures the Flux controllers and the delivery of platform components and applications.\n\nAfter bootstrap, changes to the Flux configuration and version upgrades are done by\nmodifying the [FluxInstance](https://github.com/controlplaneio-fluxcd/d2-fleet/blob/main/clusters/staging/flux-system/flux-instance.yaml)\nmanifest and letting Flux reconcile the changes, there is no need to run bootstrap\nagain nor connect to the cluster.\n\n### GitHub PAT Configuration\n\nIt is recommended to create a dedicated GitHub account for the Flux bot. This account will be used\nby the Flux source-controller running on clusters to authenticate with GitHub Container Registry\nto pull the OCI Artifacts.\n\nThe Flux bot account must have read access to the `d2-fleet`, `d2-infra` and `d2-apps` repositories,\nand the GitHub [Personal Access Token (classic)](https://github.com/settings/tokens) (PAT) should grant read-only access to the GitHub Container Registry\nby selecting the `read:packages` scope.\n\n### Bootstrap a Kubernetes Cluster\n\nFor testing purposes, you can create a KinD cluster and bootstrap Flux with the staging configuration\nby running the following commands:\n\n```shell\nexport GITHUB_TOKEN=\u003cFlux Bot PAT\u003e\n\nmake bootstrap-staging\n```\n\nAnother option is to use Terraform or OpenTofu. An example of how to bootstrap a cluster with Terraform\nis available in the [terraform](https://github.com/controlplaneio-fluxcd/d2-fleet/tree/main/terraform) directory.\n\n```shell\nterraform apply \\\n  -var oci_token=\"${GITHUB_TOKEN}\" \\\n  -var oci_url=\"oci://ghcr.io/controlplaneio-fluxcd/d2-fleet\" \\\n  -var oci_tag=\"latest\" \\\n  -var oci_path=\"clusters/staging\"\n```\n\nThe bootstrap performs the following steps:\n\n- Creates the `flux-system` namespace.\n- Installs the Flux Operator using Helm.\n- Creates a `FluxInstance` pointing to the `oci://ghcr.io/controlplaneio-fluxcd/d2-fleet` artifact.\n- Creates a Kubernetes image pull secret with the GitHub PAT.\n\nAfter bootstrap, the Flux Operator Helm release and the Flux instance configuration\nare being managed by Flux itself. Any changes to the Flux configuration from now on should be done\nby modifying the manifests in the\n[flux-system](https://github.com/controlplaneio-fluxcd/d2-fleet/tree/main/clusters/staging/flux-system)\ndirectory.\n\n## Onboarding Platform Components\n\nThe platform team is responsible for onboarding the platform components defined as Flux HelmReleases in the\n[d2-infra repository](https://github.com/controlplaneio-fluxcd/d2-infra) and set the dependencies\nbetween the components.\n\nPlatform components are cluster add-ons such as CRDs and their respective controllers,\nand are reconciled by Flux as the **cluster admin**.\n\nTo onboard a component from the `d2-infra` repository, the platform team must add a\nline for the component in the `.github/workflows/push-artifact.yaml` GitHub Actions\nworkflow file of the `d2-infra` repository:\n\n```yaml\n      ...\n      matrix:\n        component:\n          - cert-manager\n          - monitoring\n```\n\nWith this, an OCI Artifact will be published and signed for the new component.\n\nOn the `d2-fleet` repository, the platform team must add a new set of inputs for the\n`infra` `ResourceSet`:\n\n```yaml\n  ...\n  inputs:\n    - tenant: \"cert-manager\"\n      tag: \"${ARTIFACT_TAG}\"\n      environment: \"${ENVIRONMENT}\"\n    - tenant: \"monitoring\"\n      tag: \"${ARTIFACT_TAG}\"\n      environment: \"${ENVIRONMENT}\"\n```\n\nWith this, the set of base resources for a component will now also be created for the new component.\nThis set includes an `OCIRepository` object that points to the OCI Artifact, and two `Kustomization`\nobjects consuming the artifact, `infra-controllers` and `infra-configs`, that together configure the\nreconciliation of the new component.\n\nThe typical structure of the `d2-infra` repository is as follows:\n\n```shell\n./components/\n├── cert-manager\n│   ├── configs\n│   │   ├── base\n│   │   ├── production\n│   │   └── staging\n│   └── controllers\n│       ├── base\n│       ├── production\n│       └── staging\n└── monitoring\n    ├── configs\n    │   ├── base\n    │   ├── production\n    │   └── staging\n    └── controllers\n        ├── base\n        ├── production\n        └── staging\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcontrolplaneio-fluxcd%2Fd2-fleet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcontrolplaneio-fluxcd%2Fd2-fleet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcontrolplaneio-fluxcd%2Fd2-fleet/lists"}