From 0a9e9722c57c9ff22b451579d5346a5cfacdb065 Mon Sep 17 00:00:00 2001 From: Mac Chaffee Date: Wed, 23 Mar 2022 15:42:24 -0400 Subject: [PATCH 1/3] Add docs for proper kustomization installs --- README.md | 125 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 70 insertions(+), 55 deletions(-) diff --git a/README.md b/README.md index d983150d..76750be7 100644 --- a/README.md +++ b/README.md @@ -5,14 +5,15 @@ An [Ansible AWX](https://github.com/ansible/awx) operator for Kubernetes built with [Operator SDK](https://github.com/operator-framework/operator-sdk) and Ansible. # Table of Contents - + + * [AWX Operator](#awx-operator) * [Table of Contents](#table-of-contents) * [Purpose](#purpose) * [Usage](#usage) - * [Basic Install on minikube (beginner or testing)](#basic-install-on-minikube-beginner-or-testing) - * [Basic Install on existing cluster](#basic-install-on-existing-cluster) + * [Creating a minikube cluster for testing](#creating-a-minikube-cluster-for-testing) + * [Basic Install](#basic-install) * [Admin user account configuration](#admin-user-account-configuration) * [Network and TLS Configuration](#network-and-tls-configuration) * [Service Type](#service-type) @@ -31,12 +32,16 @@ An [Ansible AWX](https://github.com/ansible/awx) operator for Kubernetes built w * [Persisting Projects Directory](#persisting-projects-directory) * [Custom Volume and Volume Mount Options](#custom-volume-and-volume-mount-options) * [Default execution environments from private registries](#default-execution-environments-from-private-registries) + * [Control plane ee from private registry](#control-plane-ee-from-private-registry) * [Exporting Environment Variables to Containers](#exporting-environment-variables-to-containers) * [Extra Settings](#extra-settings) * [Service Account](#service-account) * [Uninstall](#uninstall) * [Upgrading](#upgrading) * [v0.14.0](#v0140) + * [Cluster-scope to Namespace-scope considerations](#cluster-scope-to-namespace-scope-considerations) + * [Project is now based on v1.x of the operator-sdk project](#project-is-now-based-on-v1x-of-the-operator-sdk-project) + * [Steps to upgrade](#steps-to-upgrade) * [Contributing](#contributing) * [Release Process](#release-process) * [Author](#author) @@ -48,11 +53,11 @@ This operator is meant to provide a more Kubernetes-native installation method f ## Usage -### Basic Install on minikube (beginner or testing) - This Kubernetes Operator is meant to be deployed in your Kubernetes cluster(s) and can manage one or more AWX instances in any namespace. -For testing purposes, the `awx-operator` can be deployed on a [Minikube](https://minikube.sigs.k8s.io/docs/) cluster. Due to different OS and hardware environments, please refer to the official Minikube documentation for further information. +### Creating a minikube cluster for testing + +If you do not have an existing cluster, the `awx-operator` can be deployed on a [Minikube](https://minikube.sigs.k8s.io/docs/) cluster for testing purposes. Due to different OS and hardware environments, please refer to the official Minikube documentation for further information. ``` $ minikube start --cpus=4 --memory=6g --addons=ingress @@ -101,46 +106,66 @@ Let's create an alias for easier usage: $ alias kubectl="minikube kubectl --" ``` -Now you need to deploy AWX Operator into your cluster. Clone this repo and `git checkout` the latest version from https://github.com/ansible/awx-operator/releases, and then run the following command: +### Basic Install + +Once you have a running Kubernetes cluster, you can deploy AWX Operator into your cluster using [Kustomize](https://kubectl.docs.kubernetes.io/guides/introduction/kustomize/). + +First, create a file called `kustomization.yaml` with the following content: + +```yaml +apiVersion: kustomize.config.k8s.io/v1beta1 +kind: Kustomization +resources: + # Find the latest tag here: https://github.com/ansible/awx-operator/releases + - github.com/ansible/awx-operator/config/default?ref=0.18.0 + +# Set the image tags to match the git version from above +images: + - name: quay.io/ansible/awx-operator + newTag: 0.18.0 + +# Specify a custom namespace in which to install AWX +namespace: awx +``` + +> **TIP:** If you need to change any of the default settings for the operator (such as resources.limits), you can add [patches](https://kubectl.docs.kubernetes.io/references/kustomize/kustomization/patches/) at the bottom of your kustomization.yaml file. + +Install the manifests by running this: ``` -$ export NAMESPACE=my-namespace -$ make deploy - /home/user/awx-operator/bin/kustomize build config/default | kubectl apply -f - - namespace/my-namespace created - customresourcedefinition.apiextensions.k8s.io/awxbackups.awx.ansible.com created - customresourcedefinition.apiextensions.k8s.io/awxrestores.awx.ansible.com created - customresourcedefinition.apiextensions.k8s.io/awxs.awx.ansible.com created - serviceaccount/awx-operator-controller-manager created - role.rbac.authorization.k8s.io/awx-operator-leader-election-role created - role.rbac.authorization.k8s.io/awx-operator-manager-role created - clusterrole.rbac.authorization.k8s.io/awx-operator-metrics-reader created - clusterrole.rbac.authorization.k8s.io/awx-operator-proxy-role created - rolebinding.rbac.authorization.k8s.io/awx-operator-leader-election-rolebinding created - rolebinding.rbac.authorization.k8s.io/awx-operator-manager-rolebinding created - clusterrolebinding.rbac.authorization.k8s.io/awx-operator-proxy-rolebinding created - configmap/awx-operator-manager-config created - service/awx-operator-controller-manager-metrics-service created - deployment.apps/awx-operator-controller-manager created +$ kustomize build . | kubectl apply -f - +namespace/machaffe created +customresourcedefinition.apiextensions.k8s.io/awxbackups.awx.ansible.com created +customresourcedefinition.apiextensions.k8s.io/awxrestores.awx.ansible.com created +customresourcedefinition.apiextensions.k8s.io/awxs.awx.ansible.com created +serviceaccount/awx-operator-controller-manager created +role.rbac.authorization.k8s.io/awx-operator-awx-manager-role created +role.rbac.authorization.k8s.io/awx-operator-leader-election-role created +clusterrole.rbac.authorization.k8s.io/awx-operator-metrics-reader created +clusterrole.rbac.authorization.k8s.io/awx-operator-proxy-role created +rolebinding.rbac.authorization.k8s.io/awx-operator-awx-manager-rolebinding created +rolebinding.rbac.authorization.k8s.io/awx-operator-leader-election-rolebinding created +clusterrolebinding.rbac.authorization.k8s.io/awx-operator-proxy-rolebinding created +configmap/awx-operator-awx-manager-config created +service/awx-operator-controller-manager-metrics-service created +deployment.apps/awx-operator-controller-manager created ``` Wait a bit and you should have the `awx-operator` running: ``` -$ kubectl get pods -n $NAMESPACE +$ kubectl get pods -n awx NAME READY STATUS RESTARTS AGE awx-operator-controller-manager-66ccd8f997-rhd4z 2/2 Running 0 11s ``` -So we don't have to keep repeating `-n $NAMESPACE`, let's set the current namespace for `kubectl`: +So we don't have to keep repeating `-n awx`, let's set the current namespace for `kubectl`: ``` -$ kubectl config set-context --current --namespace=$NAMESPACE +$ kubectl config set-context --current --namespace=awx ``` -It is important to know that when you do not set the default namespace to $NAMESPACE that the `awx-operator-controller-manager` might get confused. - -Next, create a file named `awx-demo.yml` with the suggested content below. The `metadata.name` you provide, will be the name of the resulting AWX deployment. +Next, create a file named `awx-demo.yml` in the same folder with the suggested content below. The `metadata.name` you provide will be the name of the resulting AWX deployment. **Note:** If you deploy more than one AWX instance to the same namespace, be sure to use unique names. @@ -154,17 +179,21 @@ spec: service_type: nodeport ``` -Finally, use `kubectl` to create the awx instance in your cluster: +Make sure to add this new file to the list of "resources" in your `kustomization.yaml` file: + +```yaml +... +resources: + - github.com/ansible/awx-operator/config/default?ref=0.18.0 + # Add this extra line: + - awx-demo.yaml +... +``` + +Finally, run `kustomize` again to create the AWX instance in your cluster: ``` -$ kubectl apply -f awx-demo.yml -awx.awx.ansible.com/awx-demo created -``` -Or, when you haven't set a default namespace - -``` -$ kubectl apply -f awx-demo.yml --namespace=$NAMESPACE -awx.awx.ansible.com/awx-demo created +kustomize build . | kubectl apply -f - ``` After a few minutes, the new AWX instance will be deployed. You can look at the operator pod logs in order to know where the installation process is at: @@ -206,20 +235,6 @@ For an example using the Nginx Controller in Minukube, don't miss our [demo vide [![asciicast](https://raw.githubusercontent.com/ansible/awx-operator/devel/docs/awx-demo.svg)](https://asciinema.org/a/416946) -### Basic Install on existing cluster - -For those running a whole K8S Cluster the steps to set up the awx-operator are: - -``` -$ Prepare required files -git clone https://github.com/ansible/awx-operator.git -cd awx-operator -git checkout {{ latest_released_version }} # replace variable by latest version number in releases - -$ Deploy new AWX Operator -export NAMESPACE= -make deploy -``` ### Admin user account configuration @@ -565,7 +580,7 @@ spec: You can constrain the AWX pods created by the operator to run on a certain subset of nodes. `node_selector` and `postgres_selector` constrains the AWX pods to run only on the nodes that match all the specified key/value pairs. `tolerations` and `postgres_tolerations` allow the AWX pods to be scheduled onto nodes with matching taints. -The ability to specify topologySpreadConstraints is also allowed through `topology_spread_constraints` +The ability to specify topologySpreadConstraints is also allowed through `topology_spread_constraints` | Name | Description | Default | From 375031e1f8cadb2d7c774b525cc0aa11a490a4f6 Mon Sep 17 00:00:00 2001 From: Mac Chaffee Date: Thu, 24 Mar 2022 19:18:46 -0400 Subject: [PATCH 2/3] Remove explicit tags to avoid need to bump versions Signed-off-by: Mac Chaffee --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 76750be7..ce17f22a 100644 --- a/README.md +++ b/README.md @@ -117,12 +117,12 @@ apiVersion: kustomize.config.k8s.io/v1beta1 kind: Kustomization resources: # Find the latest tag here: https://github.com/ansible/awx-operator/releases - - github.com/ansible/awx-operator/config/default?ref=0.18.0 + - github.com/ansible/awx-operator/config/default?ref= # Set the image tags to match the git version from above images: - name: quay.io/ansible/awx-operator - newTag: 0.18.0 + newTag: # Specify a custom namespace in which to install AWX namespace: awx @@ -184,7 +184,7 @@ Make sure to add this new file to the list of "resources" in your `kustomization ```yaml ... resources: - - github.com/ansible/awx-operator/config/default?ref=0.18.0 + - github.com/ansible/awx-operator/config/default?ref= # Add this extra line: - awx-demo.yaml ... From add76c159b114966886f9639f2f4062b9e9678a4 Mon Sep 17 00:00:00 2001 From: Mac Chaffee Date: Sat, 26 Mar 2022 11:53:17 -0400 Subject: [PATCH 3/3] Mention how to install Kustomize. It's recommended to install the standalone version of kustomize rather than using the version that ships with kubectl because that version is typically very old and doesn't match the docs. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index ce17f22a..4df59fa4 100644 --- a/README.md +++ b/README.md @@ -108,7 +108,7 @@ $ alias kubectl="minikube kubectl --" ### Basic Install -Once you have a running Kubernetes cluster, you can deploy AWX Operator into your cluster using [Kustomize](https://kubectl.docs.kubernetes.io/guides/introduction/kustomize/). +Once you have a running Kubernetes cluster, you can deploy AWX Operator into your cluster using [Kustomize](https://kubectl.docs.kubernetes.io/guides/introduction/kustomize/). Follow the instructions here to install the latest version of Kustomize: https://kubectl.docs.kubernetes.io/installation/kustomize/ First, create a file called `kustomization.yaml` with the following content: @@ -165,7 +165,7 @@ So we don't have to keep repeating `-n awx`, let's set the current namespace for $ kubectl config set-context --current --namespace=awx ``` -Next, create a file named `awx-demo.yml` in the same folder with the suggested content below. The `metadata.name` you provide will be the name of the resulting AWX deployment. +Next, create a file named `awx-demo.yaml` in the same folder with the suggested content below. The `metadata.name` you provide will be the name of the resulting AWX deployment. **Note:** If you deploy more than one AWX instance to the same namespace, be sure to use unique names.