internet/awx-operator
3
0
Fork 0
mirror of https://github.com/ansible/awx-operator.git synced 2026-05-07 22:02:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: overall minor renovations (#1874)

Browse Source 
* docs: simplify README.md and make index.md to refer to it
* docs: change order for pages in navigation and add missing pages
* docs: fix headings to improve navigation, transform notes to admonition, fix indentation, linting issues and minor issues
* docs: merge docs for using images from private registries
* docs: add example to integrate LDAP configuration via extra_settings_files
* Apply suggestions from code review
docs: apply suggested changes

Co-authored-by: Don Naro <dnaro@redhat.com>

* docs: update the doc site url as same as the url in https://www.ansible.com/ecosystem/
* docs: minor fixes for hpa page
* docs: expand note block
* docs: apply #1904 to README.md

---------

Co-authored-by: Don Naro <dnaro@redhat.com>
This commit is contained in:
kurokobo
2024-07-21 07:34:21 +09:00
committed by GitHub
parent 36cf9c23ea
commit 2b0221bbc6
51 changed files with 466 additions and 408 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
docs/installation/basic-install.md
View File

@@ -1,6 +1,7 @@
### Basic Install
# Basic Install
After cloning this repository, you must choose the tag to run:
```sh
git clone git@github.com:ansible/awx-operator.git
cd awx-operator
@@ -20,17 +21,23 @@ export VERSION=<tag>
export VERSION=2.7.2
```
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/ )
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/>)
> Some things may need to be configured slightly differently for different Kubernetes flavors for the networking aspects. When installing on Kind, see the [kind install docs](./kind-install.md) for more details.
!!! tip
If you don't have a Kubernetes cluster, you can use [Minikube](https://minikube.sigs.k8s.io/docs/) for testing purposes. See the [Minikube install docs](./creating-a-minikube-cluster-for-testing.md) for more details.
!!! note
Some things may need to be configured slightly differently for different Kubernetes flavors for the networking aspects. When installing on Kind, see the [kind install docs](./kind-install.md) for more details.
There is a make target you can run:
```
```sh
make deploy
```
If you have a custom operator image you have built, you can specify it with:
```
```sh
IMG=quay.io/$YOURNAMESPACE/awx-operator:$YOURTAG make deploy
```
@@ -52,11 +59,12 @@ images:
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.
!!! 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:
```
```sh
$ kubectl apply -k .
namespace/awx created
customresourcedefinition.apiextensions.k8s.io/awxbackups.awx.ansible.com created
@@ -77,7 +85,7 @@ deployment.apps/awx-operator-controller-manager created
Wait a bit and you should have the `awx-operator` running:
```
```sh
$ kubectl get pods -n awx
NAME READY STATUS RESTARTS AGE
awx-operator-controller-manager-66ccd8f997-rhd4z 2/2 Running 0 11s
@@ -85,13 +93,14 @@ awx-operator-controller-manager-66ccd8f997-rhd4z 2/2 Running 0
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
```sh
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.
**Note:** If you deploy more than one AWX instance to the same namespace, be sure to use unique names.
!!! note
If you deploy more than one AWX instance to the same namespace, be sure to use unique names.
```yaml
---
@@ -103,7 +112,8 @@ 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](../user-guide/admin-user-account-configuration.md#secret-key-configuration).
!!! tip
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](../user-guide/admin-user-account-configuration.md#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.
@@ -118,8 +128,7 @@ spec:
ingress_type: Route
```
Make sure to add this new file to the list of "resources" in your `kustomization.yaml` file:
Make sure to add this new file to the list of `resources` in your `kustomization.yaml` file:
```yaml
...
@@ -132,19 +141,13 @@ resources:
Finally, apply the changes to create the AWX instance in your cluster:
```
```sh
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:
```
```sh
$ 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
@@ -156,19 +159,19 @@ awx-demo-postgres ClusterIP None <none> 5432/TCP 4m4s
awx-demo-service NodePort 10.109.40.38 <none> 80:31006/TCP 3m56s
```
Once deployed, the AWX instance will be accessible by running:
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:
```sh
kubectl logs -f deployments/awx-operator-controller-manager -c awx-manager
```
$ minikube service -n awx awx-demo-service --url
```
Once deployed, your AWX instance should now be reachable at `http://localhost:<assigned-nodeport>/` (in this case, `http://localhost:31006/`).
By default, the admin user is `admin` and the password is available in the `<resourcename>-admin-password` secret. To retrieve the admin password, run:
```
```sh
$ 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).

21
docs/installation/creating-a-minikube-cluster-for-testing.md
View File

@@ -1,8 +1,8 @@
### Creating a minikube cluster for testing
# 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.
```
```sh
$ minikube start --cpus=4 --memory=6g --addons=ingress
😄 minikube v1.23.2 on Fedora 34
✨ Using the docker driver based on existing profile
@@ -22,7 +22,7 @@ $ minikube start --cpus=4 --memory=6g --addons=ingress
Once Minikube is deployed, check if the node(s) and `kube-apiserver` communication is working as expected.
```
```sh
$ minikube kubectl -- get nodes
NAME STATUS ROLES AGE VERSION
minikube Ready control-plane,master 113s v1.22.2
@@ -45,6 +45,17 @@ It is not required for `kubectl` to be separately installed since it comes alrea
Let's create an alias for easier usage:
```sh
alias kubectl="minikube kubectl --"
```
$ alias kubectl="minikube kubectl --"
```
Now, you can proceed with the installation of the AWX Operator and AWX. Please refer to the [Basic Install](basic-install.md) for further instructions.
!!! tip
Once your AWX has been deployed, the AWX instance will be accessible by running:
```sh
minikube service -n awx awx-demo-service --url
```
For an example using the Nginx Ingress Controller in Minikube, don't miss our [demo video](https://asciinema.org/a/416946).

2
docs/installation/helm-install-on-existing-cluster.md
View File

@@ -1,4 +1,4 @@
### Helm Install on existing cluster
# 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:

2
docs/installation/index.md
View File

@@ -1,2 +0,0 @@
The AWX Operator is meant to be deployed in your Kubernetes cluster(s) and can be used to install and manage the lifecycle of an AWX instance in the same namespace.

36
docs/installation/kind-install.md
View File

@@ -2,9 +2,9 @@
## Kind Install
Install Kind by running the following
Install Kind by running the following. Refer to the [official Kind documentation](https://kind.sigs.k8s.io/docs/user/quick-start/) for more information.
```
```sh
# For Intel Macs
[ $(uname -m) = x86_64 ] && curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.20.0/kind-darwin-amd64
# For M1 / ARM Macs
@@ -13,9 +13,6 @@ chmod +x ./kind
mv ./kind /some-dir-in-your-PATH/kind
```
> https://kind.sigs.k8s.io/docs/user/quick-start/
### Create the Kind cluster
Create a file called `kind.config`
@@ -35,40 +32,39 @@ nodes:
Then create a cluster using that config
```
```sh
kind create cluster --config=kind.config
```
Set cluster context for kubectl
```
```sh
kubectl cluster-info --context kind-kind
```
Install NGINX Ingress Controller
```
```sh
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/deploy/static/provider/kind/deploy.yaml
```
## AWX
Set the namespace context
```
```sh
kubectl config set-context --current --namespace=awx
```
Checkout the tag you want to install from
```
```sh
git checkout 2.7.2
```
Create a file named `kustomization.yaml` in the root of your local awx-operator clone. Include the following:
```
```sh
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
@@ -86,14 +82,13 @@ namespace: awx
Run the following to apply the yaml
```
```sh
kubectl apply -k .
```
Create a file called `awx-cr.yaml` with the following contents and any configuration changes you may wish to add.
```
```yaml
---
apiVersion: awx.ansible.com/v1beta1
kind: AWX
@@ -106,20 +101,19 @@ spec:
Create your AWX CR
```
```sh
kubectl create -f awx-cr.yaml
```
Your AWX instance should now be reacheable at http://localhost:32000/
> If you configured a custom nodeport_port, you can find it by running `kubectl -n awx get svc awx-demo-service`
Your AWX instance should now be reachable at <http://localhost:32000/>
!!! note
If you configured a custom `nodeport_port`, you can find it by running `kubectl -n awx get svc awx-demo-service`
## Cleanup
When you are done, you can delete all of this by running
```
```sh
kind delete cluster
```