☸️ How to Deploy a Kubernetes Workload#

This feature allows to deploy Kubernetes sys-services, i.e. operators and controllers needed in the cluster, at cluster level, and managed by the platform team.

The deployment is done via GitOps, using ArgoCD. This means that the deployment is done when new changes arrive to the deployment branch in the state GitHub repository, which is then automatically picked up by ArgoCD and deployed to the Kubernetes cluster.

Configuration#

The feature’s workflows can need the following GitHub vars, or secrets configured (at organization or repository level), to manage the access to the Helm charts registries, depending on the publication method used by the organization:

1️⃣ Only needed if HELM_CHARTS_PUBLICATION_TYPE is set to oci

2️⃣ Only needed if the registry authentication is OIDC, i.e.:

• azure_oidc using a Managed Identity.
• aws_oidc using an IAM Role.

3️⃣ Only needed if the registry authentication is not OIDC, i.e.:

• ghcr using a PAT distinct from the default actions’ GITHUB_TOKEN. Else, the action will use the GITHUB_TOKEN by default.
• generic, i.e. user & password.

See auth-oci tool documentation for more details.

:four: The docker_registries folder contains a YAML files for each registry available in the organization, with the necessary configuration.

Workflows#

The feature provides the following GitHub Actions workflows:

Validate PR#

This workflow validates changes in pull requests to ensure they meet the required standards.

Permissions:

• id-token: write: Needed for OIDC authentication to the helm charts registry, if applicable.
• contents: read: Needed to clone the repository.
• pull-requests: write: Needed to comment on the related pull request.
• packages: read: Needed to pull the Helm charts from GitHub Container Registry, if applicable.

Generate deployment#

This workflow generates deployment files (CRs) for a Kubernetes sys-service workload based on a platform and sys_service you specify. It updates your GitOps repo (watched by ArgoCD) on the deployment branch. Permissions:

• id-token: write: Needed for OIDC authentication to the helm charts registry, if applicable.
• contents: write: Needed to clone the repository and push the deployment artifacts branch against the deployment branch.
• pull-requests: write: Needed to create the pull-request against the deployment branch, and comment on it.
• packages: read: Needed to pull the Helm charts from GitHub Container Registry, if applicable.

1. 🖐️ Manual Deployment#

This workflow generates deployment files (CRs) for a Kubernetes workload based on the platform you specify. It updates your GitOps repo (watched by ArgoCD) on the deployment branch.

1.1 📋 How to Use It#

1. Update Values

   • Go to the state-sys-services repo’s default branch.
   • Edit the helm values files (e.g., in kubernetes-sys-services/<cluster>/<service>/values.yaml) with the desired changes.
   • Create a pull-request, wait for the PR Verify completion ✅ and merge it into the default branch.

2. Head to Actions tab

   • Go to the “Actions” tab on the repository.

3. Locate the Generate Kubernetes deployment Workflow

   • Find Generate deployment workflow in the list.

4. Launch It

   • Click “Run workflow”.
   • Fill in the deployment coordinates:
     • platform (e.g., my-eks-cluster).
     • sys_service (e.g., datadog).
   • Hit “Run workflow” to start.

1.2 🌟 What You Get#

• Updated Repo: Deployment manifests (CRs) are created or updated and land in a pull request against the deployment branch.
• Summary: Check the workflow logs on GitHub for details.
• Deploy: Merge the pull-request, and ArgoCD will sync the changes to the Kubernetes deployment cluster.

1.3 🛠️ Troubleshooting#

• Fails? Look at the logs or summary in GitHub Actions. Verify your platform and sys_service inputs.
• No PR? Ensure the inputs match a valid Kubernetes workload path (e.g., kubernetes-sys-services/my-platform/my-sys_service).

⚙️ Additional Configuration#

• config file: A config file can be added to the repository to select the helmfile image version and additional commands to the container before the rendering process.
  • location: .github
  • name: hydrate_k8s_config.yaml
  • content:

    # example
    image: ghcr.io/helmfile/helmfile:v1.1.0
    commands:
      - [apk, add, python]