kube-workflow

Kube-Workflow - CI on Kubernetes 🚀

schema

GitHub Action Entrypoint

Call it in review, preprod, and prod github workflows

.github/workflow/review.yaml

- uses: SocialGouv/kube-workflow@master
  with:
    environment: dev
    token: $
    kubeconfig: $
    rancherProjectId: $
    rancherProjectName: $
    # components: app hasura

Configure your project

.kube-workflow/values.yaml

# here you define variables shared by all helm subcharts/components
global: {}

# here you can configure components values
app:
  enabled: true # enable each component
  containerPort: 3000

Here is the order, the last in the list is the last applied:

From kube-workflow repository:

From your project repository:

Generate manifests

see kube manifests for your project directory

npx kube-workflow b -so

get documentation of kube-workflow cli

npx kube-workflow --help
npx kube-workflow build --help
npx kube-workflow deploy --help

pre-requisites:

Components

To see all components availables go to charts folder:

To see all availables options by component see each chart’s values.yaml file:

Components instance

You can declare as many instances as you want of a component, the name must start with the chart’s name suffixed by -, eg:

app:
  enabled: true
  host: ozensemble.fr
  redirectFrom:
    - ""
    - www.ozensemble.fr

app-2nd-instance:
  enabled: true
  probesPath: /healthz
  envFrom:
    - secretRef:
        name: ""
    - secretRef:
        name: app-sealed-secret
    - configMapRef:
        name: app-configmap

The “jobs” component

The component called “jobs” is a special component that allow you to define a full pipeline:

hasura:
  enabled: true
  needs: [db]

jobs:
  enabled: true
  runs:
    - name: db
      # use: ./.kube-workflow/jobs/create-db # local job, defined in project repository
      # use: https://github.com/SocialGouv/kube-workflow/jobs/create-db # degit full url
      use: SocialGouv/kube-workflow/jobs/create-db # degit implicit github
      with:
        pgAdminSecretRefName: pg-scaleway
    - name: seed
      needs: [hasura]
      use: SocialGouv/kube-workflow/jobs/seed-db
      with:
        seedPath: path/in/repo.sql

see jobs/create-db/use.yaml for full example. All vues from runs keys will be interpolated in the job, but you can also uses all parameters directly, except the with parameter that is reserved to be used with use and inject variable to the called job.

All others components can declare dependencies on jobs using the needs key, and all jobs can declare depencencies on other jobs and other components too, using instances names.

Mains jobs parameters are:

There is a shared storage volume between jobs of a same pipeline, it’s mounted at /workflow/ in the job execution, you can share artifacts between jobs in this directory.

Same as other components, you can define multiple instance of jobs, for example, if you want to use one pipeline from a manual triggered action.

Merge common manifests as helm templates

Every yaml file in .kube-workflow/templates will be merged with the helm Chart templates folder before the build.

All theses files can use the Helm templating syntax (or not if you don’t need it, helm template is a superset of yaml).

Both extensions yaml and yml are accepted.

Merge manifests per environment as helm templates

Every yaml files in .kube-workflow/$ENVIRONMENT/templates will be merged with the helm Chart templates folder before the build, according to the environment input (dev preprod prod).

All theses files can use the Helm templating syntax.

Usually, that’s where you put your ConfigMap and SealedSecrets ressources.

Hack the manifests

You can modify anything you want using post-renderer executable that you can put at .kube-workflow/post-renderer. This can be a simple script and use jq, or you can call kustomize from it. The post-renderer will receive manifest in json format, for easier usage with jq: /kube-workflow/post-render:

#!/bin/sh

# load into variable from standard input
manifest=$(cat /dev/stdin)

# arbitrary modify some stuf
manifest=`echo "$manifest" | jq 'select(.kind = Ingress) | .annotation.foo = "bar"'`

# output
echo "$manifest"

see jq documentation

Charts re-use

All charts are published and released as a chart repository at https://socialgouv.github.io/kube-workflow/. You can use it in your Chart.yaml as:

dependencies:
  - repository: https://socialgouv.github.io/kube-workflow/
    name: kube-workflow
    version: "1"

kube-workflow is the “umbrella hcart” (the main chart in helm jargon), it contain namespace, psp and all others components as subcharts, you can call all components from subkeys in your values, global remain at top.

Releasing

Automatic

Execute the Trigger Release workflow to trigger a new release of actions and helm charts.

Manual

Releasing follow semantic versioning using standard-version tool. Versioning can be trigerred manually on dev machine to not block rapid iteration of master branch code : just run yarn release on master branch and CHANGELOG will be feeded with informations from commits using the conventionnal commit standard, then package will be bumped, as the charts versions and commited, then tagged. Then just follow cli instruction that say: git push --follow-tags. Then the action will publish automatically new version of npm cli, and charts index.

CONTRIBUTING (developments on kube-workflow)

Test

all directories added to tests/samples are like a .kube-workflow directory in a project, it will be automatically tested when you will run yarn test. To run only one test at once you can run yarn test -t name-of-my-test. To upgrade snapshots run yarn test -u.

Contribute adding more Helm charts

New charts are welcome in folder charts/. More options on existing charts will be carefully design, in case of doubt, or if you don’t want to wait, you can hack everything using post-renderer from your repository. Feel free, then give us feedback to ensure we follow best practices and are preserving project maintainability.

Wee need:

Contribute adding more jobs

New jobs are welcome in folder jobs/

wee need:

Development resources

helm templates

to enable correct syntax recognition and coloration of yaml helm templates in vscode, enable Kubenernetes extension

Resources: