From 6e487ed29eff7f224e8dc7cd178e06c7387293ed Mon Sep 17 00:00:00 2001 From: Desmond Obisi <51109125+DesmondSanctity@users.noreply.github.com> Date: Wed, 26 Jul 2023 20:52:43 +0100 Subject: [PATCH] Docs: moved installation from readme to docs folder (#1478) --- README.md | 240 ------------------ docs/installation/basic-install.md | 152 +++++++++++ ...creating-a-minikube-cluster-for-testing.md | 50 ++++ .../helm-install-on-existing-cluster.md | 29 +++ docs/installation/installation.md | 3 + 5 files changed, 234 insertions(+), 240 deletions(-) create mode 100644 docs/installation/basic-install.md create mode 100644 docs/installation/creating-a-minikube-cluster-for-testing.md create mode 100644 docs/installation/helm-install-on-existing-cluster.md create mode 100644 docs/installation/installation.md diff --git a/README.md b/README.md index 577a67c0..c4e65579 100644 --- a/README.md +++ b/README.md @@ -18,9 +18,6 @@ NOTE: we are in the process of moving this readme into official docs in the /do * [AWX Operator](#awx-operator) * [Table of Contents](#table-of-contents) * [Usage](#usage) - * [Creating a minikube cluster for testing](#creating-a-minikube-cluster-for-testing) - * [Basic Install](#basic-install) - * [Helm Install on existing cluster](#helm-install-on-existing-cluster) * [Admin user account configuration](#admin-user-account-configuration) * [Network and TLS Configuration](#network-and-tls-configuration) * [Service Type](#service-type) @@ -72,244 +69,7 @@ NOTE: we are in the process of moving this readme into official docs in the /do -## Usage -This Kubernetes Operator is meant to be deployed in your Kubernetes cluster(s) and can manage one or more AWX instances in any namespace. - -### 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 -😄 minikube v1.23.2 on Fedora 34 -✨ Using the docker driver based on existing profile -👍 Starting control plane node minikube in cluster minikube -🚜 Pulling base image ... -🏃 Updating the running docker "minikube" container ... -🐳 Preparing Kubernetes v1.22.2 on Docker 20.10.8 ... -🔎 Verifying Kubernetes components... - ▪ Using image gcr.io/k8s-minikube/storage-provisioner:v5 - ▪ Using image k8s.gcr.io/ingress-nginx/controller:v1.0.0-beta.3 - ▪ Using image k8s.gcr.io/ingress-nginx/kube-webhook-certgen:v1.0 - ▪ Using image k8s.gcr.io/ingress-nginx/kube-webhook-certgen:v1.0 -🔎 Verifying ingress addon... -🌟 Enabled addons: storage-provisioner, default-storageclass, ingress -🏄 Done! kubectl is now configured to use "minikube" cluster and "default" namespace by default -``` - -Once Minikube is deployed, check if the node(s) and `kube-apiserver` communication is working as expected. - -``` -$ minikube kubectl -- get nodes -NAME STATUS ROLES AGE VERSION -minikube Ready control-plane,master 113s v1.22.2 - -$ minikube kubectl -- get pods -A -NAMESPACE NAME READY STATUS RESTARTS AGE -ingress-nginx ingress-nginx-admission-create--1-kk67h 0/1 Completed 0 2m1s -ingress-nginx ingress-nginx-admission-patch--1-7mp2r 0/1 Completed 1 2m1s -ingress-nginx ingress-nginx-controller-69bdbc4d57-bmwg8 1/1 Running 0 2m -kube-system coredns-78fcd69978-q7nmx 1/1 Running 0 2m -kube-system etcd-minikube 1/1 Running 0 2m12s -kube-system kube-apiserver-minikube 1/1 Running 0 2m16s -kube-system kube-controller-manager-minikube 1/1 Running 0 2m12s -kube-system kube-proxy-5mmnw 1/1 Running 0 2m1s -kube-system kube-scheduler-minikube 1/1 Running 0 2m15s -kube-system storage-provisioner 1/1 Running 0 2m11s -``` - -It is not required for `kubectl` to be separately installed since it comes already wrapped inside minikube. As demonstrated above, simply prefix `minikube kubectl --` before kubectl command, i.e. `kubectl get nodes` would become `minikube kubectl -- get nodes` - -Let's create an alias for easier usage: - -``` -$ 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/). Since kubectl version 1.14 kustomize functionality is built-in (otherwise, follow the instructions here to install the latest version of Kustomize: https://kubectl.docs.kubernetes.io/installation/kustomize/ ) - -There is a make target you can run: -``` -make deploy -``` - -If you have a custom operator image you have built, you can specify it with: -``` -IMG=quay.io/$YOURNAMESPACE/awx-operator:$YOURTAG make deploy -``` - -Otherwise, you can manually 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= - -# Set the image tags to match the git version from above -images: - - name: quay.io/ansible/awx-operator - newTag: - -# 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: - -``` -$ kubectl apply -k . -namespace/awx 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 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 awx`, let's set the current namespace for `kubectl`: - -``` -$ kubectl config set-context --current --namespace=awx -``` - -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. - -```yaml ---- -apiVersion: awx.ansible.com/v1beta1 -kind: AWX -metadata: - name: awx-demo -spec: - service_type: nodeport -``` - -> It may make sense to create and specify your own secret key for your deployment so that if the k8s secret gets deleted, it can be re-created if needed. If it is not provided, one will be auto-generated, but cannot be recovered if lost. Read more [here](#secret-key-configuration). - -If you are on Openshift, you can take advantage of Routes by specifying the following your spec. This will automatically create a Route for you with a custom hostname. This can be found on the Route section of the Openshift Console. - -```yaml ---- -apiVersion: awx.ansible.com/v1beta1 -kind: AWX -metadata: - name: awx-demo -spec: - service_type: clusterip - ingress_type: Route -``` - - -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= - # Add this extra line: - - awx-demo.yaml -... -``` - -Finally, apply the changes to create the AWX instance in your cluster: - -``` -kubectl apply -k . -``` - -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: - -``` -$ kubectl logs -f deployments/awx-operator-controller-manager -c awx-manager -``` - -After a few seconds, you should see the operator begin to create new resources: - -``` -$ kubectl get pods -l "app.kubernetes.io/managed-by=awx-operator" -NAME READY STATUS RESTARTS AGE -awx-demo-77d96f88d5-pnhr8 4/4 Running 0 3m24s -awx-demo-postgres-0 1/1 Running 0 3m34s - -$ kubectl get svc -l "app.kubernetes.io/managed-by=awx-operator" -NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE -awx-demo-postgres ClusterIP None 5432/TCP 4m4s -awx-demo-service NodePort 10.109.40.38 80:31006/TCP 3m56s -``` - -Once deployed, the AWX instance will be accessible by running: - -``` -$ minikube service -n awx awx-demo-service --url -``` - -By default, the admin user is `admin` and the password is available in the `-admin-password` secret. To retrieve the admin password, run: - -``` -$ kubectl get secret awx-demo-admin-password -o jsonpath="{.data.password}" | base64 --decode ; echo -yDL2Cx5Za94g9MvBP6B73nzVLlmfgPjR -``` - -You just completed the most basic install of an AWX instance via this operator. Congratulations!!! - -For an example using the Nginx Ingress Controller in Minikube, don't miss our [demo video](https://asciinema.org/a/416946). - - -### Helm Install on existing cluster - -For those that wish to use [Helm](https://helm.sh/) to install the awx-operator to an existing K8s cluster: - -The helm chart is generated from the `helm-chart` Makefile section using the starter files in `.helm/starter`. Consult [the documentation](.helm/starter/README.md) on how to customize the AWX resource with your own values. - -```bash -$ helm repo add awx-operator https://ansible.github.io/awx-operator/ -"awx-operator" has been added to your repositories - -$ helm repo update -Hang tight while we grab the latest from your chart repositories... -...Successfully got an update from the "awx-operator" chart repository -Update Complete. ⎈Happy Helming!⎈ - -$ helm search repo awx-operator -NAME CHART VERSION APP VERSION DESCRIPTION -awx-operator/awx-operator 0.17.1 0.17.1 A Helm chart for the AWX Operator - -$ helm install -n awx --create-namespace my-awx-operator awx-operator/awx-operator -NAME: my-awx-operator -LAST DEPLOYED: Thu Feb 17 22:09:05 2022 -NAMESPACE: default -STATUS: deployed -REVISION: 1 -TEST SUITE: None -NOTES: -Helm Chart 0.17.1 -``` ### Admin user account configuration diff --git a/docs/installation/basic-install.md b/docs/installation/basic-install.md new file mode 100644 index 00000000..3ad9d3f0 --- /dev/null +++ b/docs/installation/basic-install.md @@ -0,0 +1,152 @@ +### 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/). Since kubectl version 1.14 kustomize functionality is built-in (otherwise, follow the instructions here to install the latest version of Kustomize: https://kubectl.docs.kubernetes.io/installation/kustomize/ ) + +There is a make target you can run: +``` +make deploy +``` + +If you have a custom operator image you have built, you can specify it with: +``` +IMG=quay.io/$YOURNAMESPACE/awx-operator:$YOURTAG make deploy +``` + +Otherwise, you can manually 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= + +# Set the image tags to match the git version from above +images: + - name: quay.io/ansible/awx-operator + newTag: + +# 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: + +``` +$ kubectl apply -k . +namespace/awx 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 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 awx`, let's set the current namespace for `kubectl`: + +``` +$ kubectl config set-context --current --namespace=awx +``` + +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. + +```yaml +--- +apiVersion: awx.ansible.com/v1beta1 +kind: AWX +metadata: + name: awx-demo +spec: + service_type: nodeport +``` + +> It may make sense to create and specify your own secret key for your deployment so that if the k8s secret gets deleted, it can be re-created if needed. If it is not provided, one will be auto-generated, but cannot be recovered if lost. Read more [here](#secret-key-configuration). + +If you are on Openshift, you can take advantage of Routes by specifying the following your spec. This will automatically create a Route for you with a custom hostname. This can be found on the Route section of the Openshift Console. + +```yaml +--- +apiVersion: awx.ansible.com/v1beta1 +kind: AWX +metadata: + name: awx-demo +spec: + service_type: clusterip + ingress_type: Route +``` + + +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= + # Add this extra line: + - awx-demo.yaml +... +``` + +Finally, apply the changes to create the AWX instance in your cluster: + +``` +kubectl apply -k . +``` + +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: + +``` +$ kubectl logs -f deployments/awx-operator-controller-manager -c awx-manager +``` + +After a few seconds, you should see the operator begin to create new resources: + +``` +$ kubectl get pods -l "app.kubernetes.io/managed-by=awx-operator" +NAME READY STATUS RESTARTS AGE +awx-demo-77d96f88d5-pnhr8 4/4 Running 0 3m24s +awx-demo-postgres-0 1/1 Running 0 3m34s + +$ kubectl get svc -l "app.kubernetes.io/managed-by=awx-operator" +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +awx-demo-postgres ClusterIP None 5432/TCP 4m4s +awx-demo-service NodePort 10.109.40.38 80:31006/TCP 3m56s +``` + +Once deployed, the AWX instance will be accessible by running: + +``` +$ minikube service -n awx awx-demo-service --url +``` + +By default, the admin user is `admin` and the password is available in the `-admin-password` secret. To retrieve the admin password, run: + +``` +$ kubectl get secret awx-demo-admin-password -o jsonpath="{.data.password}" | base64 --decode ; echo +yDL2Cx5Za94g9MvBP6B73nzVLlmfgPjR +``` + +You just completed the most basic install of an AWX instance via this operator. Congratulations!!! + +For an example using the Nginx Ingress Controller in Minikube, don't miss our [demo video](https://asciinema.org/a/416946). diff --git a/docs/installation/creating-a-minikube-cluster-for-testing.md b/docs/installation/creating-a-minikube-cluster-for-testing.md new file mode 100644 index 00000000..c72b747c --- /dev/null +++ b/docs/installation/creating-a-minikube-cluster-for-testing.md @@ -0,0 +1,50 @@ +### 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 +😄 minikube v1.23.2 on Fedora 34 +✨ Using the docker driver based on existing profile +👍 Starting control plane node minikube in cluster minikube +🚜 Pulling base image ... +🏃 Updating the running docker "minikube" container ... +🐳 Preparing Kubernetes v1.22.2 on Docker 20.10.8 ... +🔎 Verifying Kubernetes components... + ▪ Using image gcr.io/k8s-minikube/storage-provisioner:v5 + ▪ Using image k8s.gcr.io/ingress-nginx/controller:v1.0.0-beta.3 + ▪ Using image k8s.gcr.io/ingress-nginx/kube-webhook-certgen:v1.0 + ▪ Using image k8s.gcr.io/ingress-nginx/kube-webhook-certgen:v1.0 +🔎 Verifying ingress addon... +🌟 Enabled addons: storage-provisioner, default-storageclass, ingress +🏄 Done! kubectl is now configured to use "minikube" cluster and "default" namespace by default +``` + +Once Minikube is deployed, check if the node(s) and `kube-apiserver` communication is working as expected. + +``` +$ minikube kubectl -- get nodes +NAME STATUS ROLES AGE VERSION +minikube Ready control-plane,master 113s v1.22.2 + +$ minikube kubectl -- get pods -A +NAMESPACE NAME READY STATUS RESTARTS AGE +ingress-nginx ingress-nginx-admission-create--1-kk67h 0/1 Completed 0 2m1s +ingress-nginx ingress-nginx-admission-patch--1-7mp2r 0/1 Completed 1 2m1s +ingress-nginx ingress-nginx-controller-69bdbc4d57-bmwg8 1/1 Running 0 2m +kube-system coredns-78fcd69978-q7nmx 1/1 Running 0 2m +kube-system etcd-minikube 1/1 Running 0 2m12s +kube-system kube-apiserver-minikube 1/1 Running 0 2m16s +kube-system kube-controller-manager-minikube 1/1 Running 0 2m12s +kube-system kube-proxy-5mmnw 1/1 Running 0 2m1s +kube-system kube-scheduler-minikube 1/1 Running 0 2m15s +kube-system storage-provisioner 1/1 Running 0 2m11s +``` + +It is not required for `kubectl` to be separately installed since it comes already wrapped inside minikube. As demonstrated above, simply prefix `minikube kubectl --` before kubectl command, i.e. `kubectl get nodes` would become `minikube kubectl -- get nodes` + +Let's create an alias for easier usage: + +``` +$ alias kubectl="minikube kubectl --" +``` diff --git a/docs/installation/helm-install-on-existing-cluster.md b/docs/installation/helm-install-on-existing-cluster.md new file mode 100644 index 00000000..6963fff5 --- /dev/null +++ b/docs/installation/helm-install-on-existing-cluster.md @@ -0,0 +1,29 @@ +### Helm Install on existing cluster + +For those that wish to use [Helm](https://helm.sh/) to install the awx-operator to an existing K8s cluster: + +The helm chart is generated from the `helm-chart` Makefile section using the starter files in `.helm/starter`. Consult [the documentation](.helm/starter/README.md) on how to customize the AWX resource with your own values. + +```bash +$ helm repo add awx-operator https://ansible.github.io/awx-operator/ +"awx-operator" has been added to your repositories + +$ helm repo update +Hang tight while we grab the latest from your chart repositories... +...Successfully got an update from the "awx-operator" chart repository +Update Complete. ⎈Happy Helming!⎈ + +$ helm search repo awx-operator +NAME CHART VERSION APP VERSION DESCRIPTION +awx-operator/awx-operator 0.17.1 0.17.1 A Helm chart for the AWX Operator + +$ helm install -n awx --create-namespace my-awx-operator awx-operator/awx-operator +NAME: my-awx-operator +LAST DEPLOYED: Thu Feb 17 22:09:05 2022 +NAMESPACE: default +STATUS: deployed +REVISION: 1 +TEST SUITE: None +NOTES: +Helm Chart 0.17.1 +``` diff --git a/docs/installation/installation.md b/docs/installation/installation.md new file mode 100644 index 00000000..cf058aaa --- /dev/null +++ b/docs/installation/installation.md @@ -0,0 +1,3 @@ +## Usage + +This Kubernetes Operator is meant to be deployed in your Kubernetes cluster(s) and can manage one or more AWX instances in any namespace.