airship/airshipctl
Code Issues Proposed changes

AIAP: Update documentation

Browse Source 
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
This commit is contained in:
Ian Howell 2021-09-08 15:13:40 -05:00 committed by James Gu
parent cde9648718
commit e241430712
9 changed files with 135 additions and 169 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

131
tools/airship-in-a-pod/README.md
View File

@ -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: <branch reference>
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: <branch reference>
- op: replace
path: "/spec/containers/4/env/6/value"
value: <airshipctl_ref>
```
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`.

4
tools/airship-in-a-pod/artifact-setup/Dockerfile
View File

@ -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

2
tools/airship-in-a-pod/artifact-setup/assets/entrypoint.sh
View File

@ -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"

2
tools/airship-in-a-pod/examples/airshipctl/kustomization.yaml
View File

@ -20,4 +20,4 @@ patchesJson6902:
version: v1 # apiVersion
kind: Pod
name: airship-in-a-pod
path: patchset.yaml
path: replacements.yaml

46
tools/airship-in-a-pod/examples/airshipctl/patchset.yaml
View File

@ -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

94
tools/airship-in-a-pod/examples/airshipctl/replacements.yaml Normal file
View File

@ -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"]

8
tools/airship-in-a-pod/examples/base/airship-in-a-pod.yaml
View File

@ -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

2
tools/airship-in-a-pod/examples/treasuremap/kustomization.yaml
View File

@ -20,4 +20,4 @@ patchesJson6902:
version: v1 # apiVersion
kind: Pod
name: airship-in-a-pod
path: patchset.yaml
path: replacements.yaml

15
tools/airship-in-a-pod/examples/treasuremap/patchset.yaml → tools/airship-in-a-pod/examples/treasuremap/replacements.yaml
View File

@ -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