decathlon/kubernetes-status-to-github repository overview

⁠Kubernetes status to GitHub Deployment

This project provides a kubernetes controller to push to GitHub the deployment status of an application deployed in Kubernetes.

⁠Table of Contents

• Why⁠
  • Test use case⁠
  • Tracing / delivery metrics use case⁠
• What it is⁠
• Setup⁠
• Use the operator⁠
  • GitHubDeployment kubernetes object⁠
  • Extraction examples⁠

⁠Why

GitHub can manage deployment and deployment history (deployment event).

For instance, here a list of environments (don't worry, this controller create them automatically)

And on an environment, we can get deployments history with their status:

⁠Test use case

If a deployment is linked to a PR, it will show on the PR!

You will notice the test-pr status to failed. This status is the result of a test triggered when a deployment is successful on the PR! (for ins tance here, the status would be success only if the curl return a string containing "Hello World")

name: test-pr

on:
  deployment_status: {}

jobs:
  test-pr:
    runs-on: [self-hosted, my-runner]
    if: github.event.deployment_status.state == 'success' && startsWith(github.event.deployment_status.environment,'pr-')
    steps:
      - run: |
          DATA=$(curl ${{ github.event.deployment_status.environment_url }})

          [[ $DATA == *"Hello World"* ]]

⁠Tracing / delivery metrics use case

If GitHub contains your deployments, you can trace your version on your environment and extract some metrics.

For instance, if you want to follow accelerate metrics⁠ you can compute the deployment frequency and using GitHub API, you ca n find PR / commits between 2 deployments.

⁠What it is

This controller will capture a status from a kubernetes object (representing your app), and send it to GitHub (in your application repository).

To do so, this controller will periodically check a kubernetes object (usually app/v1 Deployment object) to capture change. A deployment status w ill be computed -in a slightly modified kstatus way- ie: In progress, Current, Failed, Terminating, Unknown.

Once it is done, if the status has been modified, the controller will send to GitHub a new GitHub deployment status. GitHub will need at least:

• the repository
• An environment name (can be prod, staging, test, prod-europe, cluster-eu1, ... )
• A (static) point in the repository tree to attach the deployment to. This point in the git repository tree can be:
  • A tag (eg. v0.2.3)
  • A sha1 from a commit (eg. 1234567abc)

Repository and environment name are static in the configuration, The point in repository tree will be computed from an extraction rule. Usually w e simply capture the docker image tag name and extract the data from it. For instance:

• If you use a GitHub release to release your image, you may use a GitHub tag following semver and the same as docker tag. Extraction rule is sim ply to use the docker tag in this case
• You may want to deploy test image, you may create a tag following a pattern. if so, you'd better set a date/time and the short sha1 of the comm it in the tag. An extraction regexp can be used to get the sha1 commit
  • If you follow semver then you can think of a tag pattern like "1.2.3-date-sha1" (like 0.1.2-202304051523-1234567a) so that you can order the image and also find which commit has produced which image.
  • You can also use a meaningful pattern you prefer like "branchname-date-sha1" (like main-202304051523-1234567a) or "pr-prnumber-date-sha1" (l ike pr-5-202304051523-1234567a)

⁠Setup

Global setup description is available setup/setup.md⁠

⁠Use the operator

⁠GitHubDeployment kubernetes object

Now you installed the controller, you will be able to use it.

You can create a GitHubDeployment object for each application you want to track status change.

Warning: Once a status is Current (OK) for Failed(KO) the status on GitHub will not take a new value for this deployment.

This tool is not intended to be used as a monitoring system! Focus is only set on deployment phase.

The GitHubDeployment is split in 3 pieces:

• What is the kubernetes to observe (sourceRef)
• How to extract the Git tree position (the commit sha1, a tag ...) (extract)
• Where to send the deployment event (repository)

apiVersion: github.decathlon.com/v1beta1
kind: GitHubDeployment
metadata:
  name: example
spec:
  sourceRef:
    apiVersion: apps/v1
    kind: Deployment
    name: podinfo-primary
    namespace: test
  extract:  # Extract the ref on which to GitHub will create the deployment ( commit sha1, tag, etc... )
    containerName: podinfod  #  get the tag of the image of this container. If it is not set, a `jsonPath` option has to be given.
    # jsonPath: $.metadata.annotations.source-ref # a jsonPath to extract a value. Mandatory is `containerName` is not set  
    regexp: main-.*-(.*) # optional. If present, extract a substring from the tag. Capture a single group (can be named "ref")
    # template: "{}"  # optional. If present, use this template to build the GitHub ref from the extracted string. "{}" will be replaced by the e
xtract string. 
                      # For instance if you capture "1.2.3", a template like 'tag-{}' will send to GitHub a ref "tag-123"  
  repository:
    name: my-repo  # your repo name (no need to set the org/user, you can just set the repo name)
    environment: staging # the environment name. It can be anything like  production, staging, ...

If the sourceRef is supported - if the controller service account can read the source kubernetes object - (only Deployment and statefulset in the example), then a GitHub deployment will be created on every change.

The deployment will reference the ref extracted from the extract part, thanks to the regexp if provided.

⁠Extraction examples

⁠Simple get tag from a container image tag

if you have a deployment with a container image with a tag :

  spec:
    template:
      spec:
        containers:
          - name: podinfo
            image: podinfo:v1.2.3 

then when you use the extract part:

    extract:
      containerName: podinfo

A GitHub deployment will be created on the "v1.2.3" git tag (if it exists).

⁠Get a part from a container image tag

if you have a deployment with a container image with a tag :

  spec:
    template:
      spec:
        containers:
          - name: podinfo
            image: podinfo:main-123456789 

then when you use the extract part:

    extract:
      containerName: podinfo
      regexp: main-(.*)

A GitHub deployment will be created on the commit referenced by "123456789" (a sha1 in the repo).

⁠Use a template to create the ref

if you have a deployment with a container image with a tag :

  spec:
    template:
      spec:
        containers:
          - name: podinfo
            image: podinfo:main-1.2.3 

then when you use the extract part:

    extract:
      containerName: podinfo
      regexp: main-(.*)
      template: "RELEASE-{}"

A GitHub deployment will be created on the "RELEASE-1.2.3" git tag (if it exists).

⁠Extract from an annotation

if you have a deployment with an annotation :

  metadata:
    annotations:
      source-ref: 123456789

then when you use the extract part:

    extract:
      jsonPath: $.metadata.annotations.source-ref
      regexp: (.*)

A GitHub deployment will be created on the commit referenced by "123456789".