From d15077e56d853d820bed061d9b41987218670afd Mon Sep 17 00:00:00 2001 From: Vladislav Kuzmin <vkuzmin@mirantis.com> Date: Fri, 2 Apr 2021 19:23:36 +0400 Subject: [PATCH] Add documentation for KRM toolbox Change-Id: I9a84e3601df7fdfb4ef355a4b0f1b25c754ce6a5 --- krm-functions/toolbox/README.md | 71 +++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 krm-functions/toolbox/README.md diff --git a/krm-functions/toolbox/README.md b/krm-functions/toolbox/README.md new file mode 100644 index 000000000..32b1b3503 --- /dev/null +++ b/krm-functions/toolbox/README.md @@ -0,0 +1,71 @@ +# Toolbox + +This is KRM function written in `go` and uses the `kyaml` library for executing binaries inside container. It helps to run scripts in container as a `airshipctl` phase. +The toolbox image has pre-installed `sh` shell,`kubectl` and `calicoctl`. + +## How to run your script as `airshipctl` phase + +`NOTE`: All file paths in the following steps depend on the site you are working with and differ depending on the environment. + +1. Create a phase document (kind: Phase) + + apiVersion: airshipit.org/v1alpha1 + kind: Phase + metadata: + name: kubectl-wait-node-ephemeral + clusterName: ephemeral-cluster + config: + executorRef: + apiVersion: airshipit.org/v1alpha1 + kind: GenericContainer + name: kubectl-get-node + +2. Create executor document (kind: GenericContainer). The [executor](https://github.com/airshipit/airshipctl/blob/master/manifests/phases/executors.yaml) use `configRef` to reference `ConfigMap` that will be generated using `configMapGenerator`. `configRef` must reference a Kubernetes ConfigMap with data key `script` with the script you want to execute. You can use kustomize [`configMapGenerator`](https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/configmapgenerator/#configmap-from-file) to create ConfigMaps ([see example](https://github.com/airshipit/airshipctl/blob/master/manifests/function/phase-helpers/wait_node/kustomization.yaml)). + + apiVersion: airshipit.org/v1alpha1 + kind: GenericContainer + metadata: + name: kubectl-get-node + labels: + airshipit.org/deploy-k8s: "false" + spec: + type: krm + image: quay.io/airshipit/toolbox:latest + hostNetwork: true + envVars + MY_ENV # airshipctl will populate this value from your current env, you can pass credentials like this + MY_ENV_TWO="my-value" + configRef: + kind: ConfigMap + name: kubectl-get-node + apiVersion: v1 + +3. Add your script as a ConfigMap. Scripts inside container have access to site kubeconfig in `${KUBECONFIG}` and to context of the cluster in `${KCTL_CONTEXT}` environment variables. + + apiVersion: v1 + kind: ConfigMap + metadata: + name: kubectl-get-node + data: + script: | + #!/bin/sh + calicoctl apply --context ${KTCL_CONTEXT} -f $RENDERED_BUNDLE_PATH + kubectl apply --context ${KTCL_CONTEXT} -f $RENDERED_BUNDLE_PATH + + 1. add kustomize resources + 2. include them into PhaseConfigBundle + +4. Make sure it is added to the bundle: + 1. `airshipctl phase render --source config -k ConfigMap` find your configmap in the output + 2. `airshipctl phase render --source config -k Phase` find your phase in output + 3. `airshipctl phase render --source config -k GenericContainer` find your executor in output + +5) Run your phase: +`airshipctl phase run kubectl-wait-node-ephemeral` + +## Input bundle usage + +The KRM function writes to filesystem input bundle specified in `documentEntryPoint` in phase declaration and imports the path to this bundle in `RENDERED_BUNDLE_PATH` environment variable. For example it can be used with `calicoctl` as `calicoctl apply -f $RENDERED_BUNDLE_PATH` + +## Important notes +The script must write to STDOUT valid yaml or redirect output to STDERR otherwise phase will fail with `mapping values are not allowed in this context`