The following guide is to help set up continuous integration and deployment (CI/CD) for an application running on a cluster set up with Okctl.

For this example and in the reference app we will be using GitHub actions

Prerequisites

It is assumed that you already have set up a cluster and that you have applied your application so that it runs there.

Now you are ready to set up continuous integration so that every push to main will deploy your app to your dev cluster, and a tag to main will deploy your app to your production cluster.

You need an IAM user with credentials that you can use for Github actions. You need to create credentials for both your development and production environment.

GitHub repositories used in this guide as a working example:

  1. Application repository
  2. IAC repo (note: visible for internal users only, but this is the same as your Okctl IAC repository)

Generate a secret key in your IAC repo

# We will generate a key inside a separate secret directory to ensure it will not get mixed up with anything else
mkdir secret
# Gitignore that directory, so there will be no accidental commits
echo secret/* >> .gitignore

cd secret
# We use stronger encryption than a default key for added security
# Create key without password
ssh-keygen -t rsa -b 4096 -f cluster_deploy_key -C git@github.com:oslokommune/okctl-reference-iac.git

NOTE: The -C parameter of the ssh-keygen command, which is the comment for the public-key, needs to be the git@github address for your IAC repo, this is because it will be needed by GitHub actions later.

  1. Go to Settings -> Secrets on your application repository on GitHub
  2. Add a repository secret (it will be the same for dev and production) named CLUSTER_DEPLOY_KEY, paste the content of cluster_deploy_key (the private key) that you generated earlier
  3. Go to Settings -> Environments (only available in GitHub enterprise) and create a dev and a prod environment
  4. For each environment, create environment secrets for AWS_ECR_ACCESS_KEY_ID and AWS_ECR_ACCESS_KEY_SECRET. Here you will place values for AWS_ACCESS_KEY_ID and AWS_ACCESS_KEY_SECRET that you created earlier for each account
  5. Go to Settings -> Deploy keys in your IAC repo on GitHub and add a new deploy key called cluster_deploy_key, using the value in cluster_deploy_key.pub, that you generated earlier. NOTE: Make sure you check the Allow write access checkbox.

Setup GitHub actions workflow files

Use templates found here.

You need to edit the following:

  • jobs -> docker-build-push -> steps[0] -> with -> aws-region if you run somewhere else than Ireland
  • jobs -> docker-build-push -> steps[3] -> env -> ECR_REPOSITORY name of your ECR repositroy, i.e. okctl-reference-app
  • jobs -> update-tag -> steps[0] -> with -> repository your IAC-repository, i.e oslokommune/okctl-reference-iac
  • jobs -> update-tag -> steps[2] -> env -> CONTAINER_NAME name of the container, i.e kotlin-test-app
  • jobs -> update-tag -> steps[2] -> env -> DEPLOYMENT_YAML_FILE location of overlay deployment patch file: i.e infrastructure/applications/okctl-reference-app/overlays/okctl-reference-dev/deployment-patch.json

Conclusion

With the above steps, you can now simply do a push to your application repository's main branch, and the change will be automatically deployed to your cluster.