From e2414307127b6b8c3b6241bb6e506ab0f3c34ef1 Mon Sep 17 00:00:00 2001 From: Ian Howell Date: Wed, 8 Sep 2021 15:13:40 -0500 Subject: [PATCH] AIAP: Update documentation This updates the documentation for working with AIAP. This includes changes to the README as well as adding all configurable values to the examples (having their default values). Change-Id: I7c1b92d6a324b0fbd07f27ec0607fc62765c4fa2 --- tools/airship-in-a-pod/README.md | 131 +++++------------- .../artifact-setup/Dockerfile | 4 +- .../artifact-setup/assets/entrypoint.sh | 2 +- .../examples/airshipctl/kustomization.yaml | 2 +- .../examples/airshipctl/patchset.yaml | 46 ------ .../examples/airshipctl/replacements.yaml | 94 +++++++++++++ .../examples/base/airship-in-a-pod.yaml | 8 +- .../examples/treasuremap/kustomization.yaml | 2 +- .../{patchset.yaml => replacements.yaml} | 15 -- 9 files changed, 135 insertions(+), 169 deletions(-) delete mode 100644 tools/airship-in-a-pod/examples/airshipctl/patchset.yaml create mode 100644 tools/airship-in-a-pod/examples/airshipctl/replacements.yaml rename tools/airship-in-a-pod/examples/treasuremap/{patchset.yaml => replacements.yaml} (76%) diff --git a/tools/airship-in-a-pod/README.md b/tools/airship-in-a-pod/README.md index d301ff77b..768e31fbc 100644 --- a/tools/airship-in-a-pod/README.md +++ b/tools/airship-in-a-pod/README.md @@ -4,14 +4,14 @@ Airship in a pod is a Kubernetes pod definition which describes all of the components required to deploy a fully functioning Airship 2 deployment. The pod consists of the following "Task" containers: -* `artifact-setup`: This container builds the airshipctl binary and makes it - available to the other containers. Also, based on the configuration provided - in the airship-in-a-pod manifest, airshipctl/treasuremap(based on the usecase) git repositories - will be downloaded and the required tag or commitId will be checked out. +* `artifact-setup`: This container collects the airshipctl binary repo, builds + the airshipctl binary (and associated kustomize plugins), and makes them + available to the other containers * `infra-builder`: This container creates the various virtual networks and machines required for an Airship deployment * `runner`: The runner container is the "meat" of the pod, and executes the - deployment + deployment. It sets up a customized airshipctl config file, then uses + airshipctl to pull the specified manifests and execute the deployment The pod also contains the following "Support" containers: @@ -43,21 +43,14 @@ the script. ### Nested Virtualisation -If deployment is done on a VM, ensure that nested virtualization is enabled. - -### Setup shared directory - -Create the following directory with appropriate r+w permissions. - -``` -sudo mkdir /opt/.airship -``` +If deployment is done on a VM, ensure that nested virtualisation is enabled. ### Environment variable setup If you are within a proxy environment, ensure that the following environment variables are defined, and NO_PROXY has the IP address which minikube uses. -For retrieving minikube ip refer: [minikube-ip](https://minikube.sigs.k8s.io/docs/commands/ip/) +Check the [minikube documentation](https://minikube.sigs.k8s.io/docs/commands/ip/) +for retrieving the minikube ip. ``` export HTTP_PROXY=http://username:password@host:port @@ -79,110 +72,55 @@ Within the environment, with appropriate env variables set, run the following co sudo -E minikube start --driver=none ``` -Refer [minikube](https://minikube.sigs.k8s.io/docs/start/)for more details. +Refer to the [minikube documentation](https://minikube.sigs.k8s.io/docs/start/) for more details. ## Usage Since Airship in a Pod is just a pod definition, deploying and using it is as -simple as deploying and using any Kubernetes pod with kustomize tool. +simple as deploying and using any other Kubernetes pod with `kubectl apply -f`. +The base pod definition can be found +[here](https://github.com/airshipit/airshipctl/tree/master/tools/airship-in-a-pod/examples/base) +and deploys using the current master `airshipctl` binary and current master +[test site](https://github.com/airshipit/airshipctl/tree/master/manifests/site/test-site). -### Pod configuration +### Pod configuration -The below section provides steps to configure site with [airshipctl](https://github.com/airshipit/airshipctl)/[treasuremap](https://github.com/airshipit/treasuremap) manifests. - -#### For airshipctl - -Within the examples/airshipctl directory, update the existing patchset.yaml -file to reflect the airshipctl branch reference as required. - -filepath : airshipctl/tools/airship-in-a-pod/examples/airshipctl/patchset.yaml +Further configuration can be applied to the pod definition via +[`kustomize`](https://kustomize.io/). Options that can be configured can be +found in the [airshipctl example](https://github.com/airshipit/airshipctl/blob/master/tools/airship-in-a-pod/examples/airshipctl/replacements.yaml). +You may choose to either modify one of the examples or create your own. +Once you've created the desired configuration, the kustomized pod can be deployed with the following: ``` -- op: replace - path: "/spec/containers/4/env/4/value" - value: +kustomize build ${PATH_TO_KUSTOMIZATION} | kubectl apply -f - ``` -#### For treasuremap +### Interacting with the Pod -For treasuremap related manifests, use the patchset.yaml from -examples/treasuremap and update the following to reflect -the treasuremap branch reference and the pinned airshipctl reference -as required. The pinned airshipctl reference is the tag/commitId with -which treasuremap is tested and found working satisfactorily. This -could be found listed as 'AIRSHIPCTL_REF' attribute under the zuul.d -directory of treasuremap repository. - -filepath : airshipctl/tools/airship-in-a-pod/examples/treasuremap/patchset.yaml - -``` -- op: replace - path: "/spec/containers/4/env/4/value" - value: - -- op: replace - path: "/spec/containers/4/env/6/value" - value: - -``` - -For more details, please consult the examples directory. - -### Deploy the Pod - -Once patchset.yaml for either airshipctl/treasuremap is ready, run the following -command against the running minikube cluster as shown below. - -For example to run AIAP with treasuremap manifests, run the following commands. - -``` -cd tools/airship-in-a-pod/examples/{either airshipctl or treasuremap} -kustomize build . | kubectl apply -f - - -``` - -### View Pod Logs +For a quick rundown of what a particular container is doing, simply check the logs for that container. ``` +# $CONTAINER is one of [runner infra-builder artifact-setup libvirt sushy dind nginx] kubectl logs airship-in-a-pod -c $CONTAINER ``` -### Interact with the Pod +For a deeper dive, consider `exec`ing into one of the containers. ``` +# $CONTAINER is one of [runner infra-builder artifact-setup libvirt sushy dind nginx] kubectl exec -it airship-in-a-pod -c $CONTAINER -- bash ``` -where `$CONTAINER` is one of the containers listed above. - -### Inspect Cluster - -Once AIAP is fully installed with a target cluster (air-target-1 and air-worker-1 nodes) -installed and running, the cluster could be monitored using the following steps. - -#### Log into the runner container - -``` -kubectl exec -it airship-in-a-pod -c runner -- bash -``` - -Run the .profile file using the following command to run kubectl/airshipctl commands -as below. - -``` -source ~/.profile - -``` - -To run kubectl commands on Target cluster, use --kubeconfig and --context params -within kubectl as below. - -``` -kubectl --kubeconfig /root/.airship/kubeconfig --context target-cluster get pods -A' -``` +#### Interacting with the Nodes +If you would like to interact with the nodes used in the deployment, you should +first prevent the runner container from exiting (check the examples/airshipctl +replacements for the option to do this). While the runner container is alive, +`exec` into it using the above command. The `kubectl` tool can then be used to +interact with a cluster. Choose a context from `kubectl config get-contexts` +and switch to it via `kubectl config use-context ${MY_CONTEXT}`. ### Output @@ -194,7 +132,6 @@ Airship-in-a-pod produces the following outputs: These artifacts are placed at `ARTIFACTS_DIR` (defaults to /opt/aiap-artifacts`). - ### Caching As it can be cumbersome and time-consuming to build and rebuild binaries and @@ -205,7 +142,7 @@ caching: * If using a cached `airshipctl`, the `airshipctl` binary must be stored in the `$CACHE_DIR/airshipctl/bin/` directory, and the developer must have set - `USE_CACHED_ARTIFACTS` to `true`. + `USE_CACHED_AIRSHIPCTL` to `true`. * If using a cached ephemeral iso, the iso must first be contained in a tarball named `iso.tar.gz`, must be stored in the `$CACHE_DIR/` directory, and the developer must have set `USE_CACHED_ISO` to `true`. diff --git a/tools/airship-in-a-pod/artifact-setup/Dockerfile b/tools/airship-in-a-pod/artifact-setup/Dockerfile index b3322aaa7..66f72c3db 100644 --- a/tools/airship-in-a-pod/artifact-setup/Dockerfile +++ b/tools/airship-in-a-pod/artifact-setup/Dockerfile @@ -4,8 +4,8 @@ FROM ${BASE_IMAGE} SHELL ["bash", "-exc"] ENV DEBIAN_FRONTEND noninteractive -ARG USE_CACHED_ARTIFACTS="false" -ENV USE_CACHED_ARTIFACTS=$USE_CACHED_ARTIFACTS +ARG USE_CACHED_AIRSHIPCTL="false" +ENV USE_CACHED_AIRSHIPCTL=$USE_CACHED_AIRSHIPCTL ARG AIRSHIPCTL_REPO_URL=https://opendev.org/airship/airshipctl ENV AIRSHIPCTL_REPO_URL=$AIRSHIPCTL_REPO_URL diff --git a/tools/airship-in-a-pod/artifact-setup/assets/entrypoint.sh b/tools/airship-in-a-pod/artifact-setup/assets/entrypoint.sh index 50d9d4217..c8527304b 100755 --- a/tools/airship-in-a-pod/artifact-setup/assets/entrypoint.sh +++ b/tools/airship-in-a-pod/artifact-setup/assets/entrypoint.sh @@ -39,7 +39,7 @@ function cloneRepo() { git checkout FETCH_HEAD } -if [[ "$USE_CACHED_ARTIFACTS" = "true" ]] +if [[ "$USE_CACHED_AIRSHIPCTL" = "true" ]] then printf "Using cached airshipctl\n" cp -r "$CACHE_DIR/*" "$ARTIFACTS_DIR" diff --git a/tools/airship-in-a-pod/examples/airshipctl/kustomization.yaml b/tools/airship-in-a-pod/examples/airshipctl/kustomization.yaml index 090672448..408ebe6e0 100644 --- a/tools/airship-in-a-pod/examples/airshipctl/kustomization.yaml +++ b/tools/airship-in-a-pod/examples/airshipctl/kustomization.yaml @@ -20,4 +20,4 @@ patchesJson6902: version: v1 # apiVersion kind: Pod name: airship-in-a-pod - path: patchset.yaml + path: replacements.yaml diff --git a/tools/airship-in-a-pod/examples/airshipctl/patchset.yaml b/tools/airship-in-a-pod/examples/airshipctl/patchset.yaml deleted file mode 100644 index 493ec12a9..000000000 --- a/tools/airship-in-a-pod/examples/airshipctl/patchset.yaml +++ /dev/null @@ -1,46 +0,0 @@ -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -# This is the location from which to clone the airshipctl binary repo -- op: replace - path: "/spec/containers/4/env/3/value" - value: https://opendev.org/airship/airshipctl - -# This is the ref to checkout for the airshipctl binary repo -- op: replace - path: "/spec/containers/4/env/4/value" - value: master - -# This is the location from which to clone the manifest documents repo -- op: replace - path: "/spec/containers/6/env/3/value" - value: https://opendev.org/airship/airshipctl - -# This is the branch or sha to checkout for the manifest documents repo -- op: replace - path: "/spec/containers/6/env/4/value" - value: master - -# This is the ref to checkout for the manifest documents repo -# Note that this will take precedence over the branch if specified above -- op: replace - path: "/spec/containers/6/env/5/value" - value: - -# for local testing -#- op: add -# path: "/spec/containers/4/imagePullPolicy" -# value: Never -# -#- op: add -# path: "/spec/containers/6/imagePullPolicy" -# value: Never diff --git a/tools/airship-in-a-pod/examples/airshipctl/replacements.yaml b/tools/airship-in-a-pod/examples/airshipctl/replacements.yaml new file mode 100644 index 000000000..018f04733 --- /dev/null +++ b/tools/airship-in-a-pod/examples/airshipctl/replacements.yaml @@ -0,0 +1,94 @@ +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# This is the location from which to clone the airshipctl binary repo +- op: replace + path: "/spec/containers/4/env/3/value" + value: https://opendev.org/airship/airshipctl + +# This is the ref to checkout for the airshipctl binary repo +- op: replace + path: "/spec/containers/4/env/4/value" + value: master + +# This is the location from which to clone the manifest documents repo +- op: replace + path: "/spec/containers/6/env/3/value" + value: https://opendev.org/airship/airshipctl + +# This is the branch or sha to checkout for the manifest documents repo +- op: replace + path: "/spec/containers/6/env/4/value" + value: master + +# This is the ref to checkout for the manifest documents repo +# Note that this will take precedence over the branch if specified above +- op: replace + path: "/spec/containers/6/env/5/value" + value: + +# The following relate to authorization for pulling the manifest repository +# This is the type of authorization to use. Currently supported types are +# [none http-basic ssh-pass] +- op: replace + path: "/spec/containers/6/env/10/value" + value: none +# The username to use when using the https protocol (basic-auth) +- op: replace + path: "/spec/containers/6/env/11/value" + value: none +# The password to use when using the https protocol (basic-auth) +- op: replace + path: "/spec/containers/6/env/12/value" + value: none +# The password to use when using the git protocol (ssh-key) +- op: replace + path: "/spec/containers/6/env/13/value" + value: + +# This is the location on the host machine of the artifacts directory. Note +# that it should be the same across containers +- op: replace + path: "/spec/containers/4/env/2/value" + value: /opt/aiap-artifacts +- op: replace + path: "/spec/containers/5/env/1/value" + value: /opt/aiap-artifacts +- op: replace + path: "/spec/containers/6/env/1/value" + value: /opt/aiap-artifacts + +# This is the location on the host machine of the cache directory. Note that it +# should be the same across containers +- op: replace + path: "/spec/containers/4/env/0/value" + value: /opt/aiap-cache +- op: replace + path: "/spec/containers/5/env/0/value" + value: /opt/aiap-cache +- op: replace + path: "/spec/containers/6/env/0/value" + value: /opt/aiap-cache +# Set true to use a cached airshipctl binary +- op: replace + path: "/spec/containers/4/env/1/value" + value: "false" +# Set true to use a cached ephemeral iso +- op: replace + path: "/spec/containers/6/env/2/value" + value: "false" + +# Uncomment the following to keep the runner container alive. This can be +# useful for debugging purposes. +# - op: replace +# path: "/spec/containers/6/command" +# value: ["bash", "-cex", "/entrypoint || sleep infinity"] diff --git a/tools/airship-in-a-pod/examples/base/airship-in-a-pod.yaml b/tools/airship-in-a-pod/examples/base/airship-in-a-pod.yaml index 2ce589eda..1fad04d93 100644 --- a/tools/airship-in-a-pod/examples/base/airship-in-a-pod.yaml +++ b/tools/airship-in-a-pod/examples/base/airship-in-a-pod.yaml @@ -216,7 +216,7 @@ spec: env: - name: CACHE_DIR value: /opt/aiap-cache - - name: USE_CACHED_ARTIFACTS + - name: USE_CACHED_AIRSHIPCTL value: "false" - name: ARTIFACTS_DIR value: /opt/aiap-artifacts @@ -348,16 +348,12 @@ spec: value: - name: AIRSHIP_CONFIG_MANIFEST_REPO_AUTH_TYPE value: "none" - - name: AIRSHIP_CONFIG_MANIFEST_REPO_AUTH_KEY_PASSWORD - value: "" - - name: AIRSHIP_CONFIG_MANIFEST_REPO_AUTH_KEY_PATH + - name: AIRSHIP_CONFIG_MANIFEST_REPO_AUTH_USERNAME value: "" - name: AIRSHIP_CONFIG_MANIFEST_REPO_AUTH_HTTP_PASSWORD value: "" - name: AIRSHIP_CONFIG_MANIFEST_REPO_AUTH_SSH_PASSWORD value: "" - - name: AIRSHIP_CONFIG_MANIFEST_REPO_AUTH_USERNAME - value: "" volumeMounts: - name: cache diff --git a/tools/airship-in-a-pod/examples/treasuremap/kustomization.yaml b/tools/airship-in-a-pod/examples/treasuremap/kustomization.yaml index 090672448..408ebe6e0 100644 --- a/tools/airship-in-a-pod/examples/treasuremap/kustomization.yaml +++ b/tools/airship-in-a-pod/examples/treasuremap/kustomization.yaml @@ -20,4 +20,4 @@ patchesJson6902: version: v1 # apiVersion kind: Pod name: airship-in-a-pod - path: patchset.yaml + path: replacements.yaml diff --git a/tools/airship-in-a-pod/examples/treasuremap/patchset.yaml b/tools/airship-in-a-pod/examples/treasuremap/replacements.yaml similarity index 76% rename from tools/airship-in-a-pod/examples/treasuremap/patchset.yaml rename to tools/airship-in-a-pod/examples/treasuremap/replacements.yaml index 651fab9db..cceb7400c 100644 --- a/tools/airship-in-a-pod/examples/treasuremap/patchset.yaml +++ b/tools/airship-in-a-pod/examples/treasuremap/replacements.yaml @@ -29,18 +29,3 @@ - op: replace path: "/spec/containers/6/env/4/value" value: 63c1faf718fd3341fc5bd975e575e3cf41647206 - -# This is the ref to checkout for the manifest documents repo -# Note that this will take precedence over the branch if specified above -- op: replace - path: "/spec/containers/6/env/5/value" - value: - -# for local testing -#- op: add -# path: "/spec/containers/4/imagePullPolicy" -# value: Never -# -#- op: add -# path: "/spec/containers/6/imagePullPolicy" -# value: Never