From c67869d755e4ccfc3470b8a7599c22459da2fe3c Mon Sep 17 00:00:00 2001 From: Christian Adams Date: Wed, 2 Aug 2023 16:24:15 -0400 Subject: [PATCH] Add Table of Contents for nested doc files (#1508) --- README.md | 70 +++++----- docs/{ => troubleshooting}/debugging.md | 0 .../advanced-configuration/debugging.md | 127 ------------------ 3 files changed, 35 insertions(+), 162 deletions(-) rename docs/{ => troubleshooting}/debugging.md (100%) delete mode 100644 docs/user-guide/advanced-configuration/debugging.md diff --git a/README.md b/README.md index aa314379f..cb87f2367 100644 --- a/README.md +++ b/README.md @@ -38,48 +38,48 @@ Table of Contents All of our usage and configuration docs are nested in the `docs/` directory. Below is a Table of Contents for those. - Introduction - - [Introduction](./docs/introduction.md) + - [Introduction](./docs/introduction/introduction.md) - Contributors Guide - - [Code of Conduct](./docs/code-of-conduct.md) - - [Get Involved](./docs/get-involved.md) - - [Contributing](./docs/contributing.md) - - [Release Process](./docs/release-process.md) - - [Authors](./docs/author.md) + - [Code of Conduct](./docs/contributors-guide/code-of-conduct.md) + - [Get Involved](./docs/contributors-guide/get-involved.md) + - [Contributing](./docs/contributors-guide/contributing.md) + - [Release Process](./docs/contributors-guide/release-process.md) + - [Authors](./docs/contributors-guide/author.md) - Installation - - [Basic Install](./docs/basic-install.md) + - [Basic Install](./docs/installation/basic-install.md) - [Creating a Minikube cluster for testing](./docs/creating-a-minikube-cluster-for-testing.md) - - [Installation](./docs/installation.md) - - [Helm Install](./docs/helm-install-on-existing-cluster.md) -- [Migration](./docs/migration.md) -- [Uninstall](./docs/uninstall.md) + - [Installation](./docs/installation/installation.md) + - [Helm Install](./docs/installation/helm-install-on-existing-cluster.md) +- [Migration](./docs/migration/migration.md) +- [Uninstall](./docs/uninstall/uninstall.md) - User Guide - - [Admin User Configuration](./docs/admin-user-account-configuration.md) - - [Database Configuration](./docs/database-configuration.md) - - [Network and TLS Configuration](./docs/network-and-tls-configuration.md) + - [Admin User Configuration](./docs/user-guide/admin-user-account-configuration.md) + - [Database Configuration](./docs/user-guide/database-configuration.md) + - [Network and TLS Configuration](./docs/user-guide/network-and-tls-configuration.md) - Advanced Configuration - [No Log](./docs/no-log.md) - - [Deploy a Specific Version of AWX](./docs/deploying-a-specific-version-of-awx.md) - - [Resource Requirements](./docs/containers-resource-requirements.md) - - [Extra Settings](./docs/extra-settings.md) - - [Environment Variables](./docs/exporting-environment-variables-to-containers.md) - - [Custom Labels](./docs/labeling-operator-managed-objects.md) - - [Custom Volumes](./docs/custom-volume-and-volume-mount-options.md) - - [Scaling Deployments](./docs/scaling-the-web-and-task-pods-independently.md) - - [Auto Update Upon Operator Upgrade](./docs/auto-upgrade.md) - - [Termination Grace Period](./docs/pods-termination-grace-period.md) - - [Node Selector for Deployments](./docs/assigning-awx-pods-to-specific-nodes.md) - - [Default EE from Private Registries](./docs/default-execution-environments-from-private-registries.md) - - [CSRF Cookie Secure](./docs/csrf-cookie-secure-setting.md) - - [Disable IPv6](./docs/disable-ipv6.md) - - [LDAP](./docs/enabling-ldap-integration-at-awx-bootstrap.md) - - [Priority Clases](./docs/priority-classes.md) - - [Priveleged Tasks](./docs/privileged-tasks.md) - - [Redis Container Capabilities](./docs/redis-container-capabilities.md) - - [Trusting a Custom Certificate Authority](./docs/trusting-a-custom-certificate-authority.md) - - [Service Account](./docs/service-account.md) - - [Persisting the Projects Directory](./docs/persisting-projects-directory.md) + - [Deploy a Specific Version of AWX](./docs/user-guide/advanced-configuration/deploying-a-specific-version-of-awx.md) + - [Resource Requirements](./docs/user-guide/advanced-configuration/containers-resource-requirements.md) + - [Extra Settings](./docs/user-guide/advanced-configuration/extra-settings.md) + - [Environment Variables](./docs/user-guide/advanced-configuration/exporting-environment-variables-to-containers.md) + - [Custom Labels](./docs/user-guide/advanced-configuration/labeling-operator-managed-objects.md) + - [Custom Volumes](./docs/user-guide/advanced-configuration/custom-volume-and-volume-mount-options.md) + - [Scaling Deployments](./docs/user-guide/advanced-configuration/scaling-the-web-and-task-pods-independently.md) + - [Auto Update Upon Operator Upgrade](./docs/user-guide/advanced-configuration/auto-upgrade.md) + - [Termination Grace Period](./docs/user-guide/advanced-configuration/pods-termination-grace-period.md) + - [Node Selector for Deployments](./docs/user-guide/advanced-configuration/assigning-awx-pods-to-specific-nodes.md) + - [Default EE from Private Registries](./docs/user-guide/advanced-configuration/default-execution-environments-from-private-registries.md) + - [CSRF Cookie Secure](./docs/user-guide/advanced-configuration/csrf-cookie-secure-setting.md) + - [Disable IPv6](./docs/user-guide/advanced-configuration/disable-ipv6.md) + - [LDAP](./docs/user-guide/advanced-configuration/enabling-ldap-integration-at-awx-bootstrap.md) + - [Priority Clases](./docs/user-guide/advanced-configuration/priority-classes.md) + - [Priveleged Tasks](./docs/user-guide/advanced-configuration/privileged-tasks.md) + - [Redis Container Capabilities](./docs/user-guide/advanced-configuration/redis-container-capabilities.md) + - [Trusting a Custom Certificate Authority](./docs/user-guide/advanced-configuration/trusting-a-custom-certificate-authority.md) + - [Service Account](./docs/user-guide/advanced-configuration/service-account.md) + - [Persisting the Projects Directory](./docs/user-guide/advanced-configuration/persisting-projects-directory.md) - Troubleshooting - - [General Debugging](./docs/debugging.md) + - [General Debugging](./docs/troubleshooting/debugging.md) ## Contributing diff --git a/docs/debugging.md b/docs/troubleshooting/debugging.md similarity index 100% rename from docs/debugging.md rename to docs/troubleshooting/debugging.md diff --git a/docs/user-guide/advanced-configuration/debugging.md b/docs/user-guide/advanced-configuration/debugging.md deleted file mode 100644 index 8654b2a34..000000000 --- a/docs/user-guide/advanced-configuration/debugging.md +++ /dev/null @@ -1,127 +0,0 @@ -# Debugging the AWX Operator - -## General Debugging - -When the operator is deploying AWX, it is running the `installer` role inside the operator container. If the AWX CR's status is `Failed`, it is often useful to look at the awx-operator container logs, which shows the output of the installer role. To see these logs, run: - -``` -kubectl logs deployments/awx-operator-controller-manager -c awx-manager -f -``` - -### Inspect k8s Resources - -Past that, it is often useful to inspect various resources the AWX Operator manages like: -* awx -* awxbackup -* awxrestore -* pod -* deployment -* pvc -* service -* ingress -* route -* secrets -* serviceaccount - -And if installing via OperatorHub and OLM: -* subscription -* csv -* installPlan -* catalogSource - -To inspect these resources you can use these commands - -``` -# Inspecting k8s resources -kubectl describe -n -kubectl get -n -o yaml -kubectl logs -n - -# Inspecting Pods -kubectl exec -it -n -``` - - -### Configure No Log - -It is possible to show task output for debugging by setting no_log to false on the AWX CR spec. -This will show output in the awx-operator logs for any failed tasks where no_log was set to true. - -For example: - -``` ---- -apiVersion: awx.ansible.com/v1beta1 -kind: AWX -metadata: - name: awx-demo -spec: - service_type: nodeport - no_log: false # <------------ - -``` - -## Iterating on the installer without deploying the operator - -Go through the [normal basic install](https://github.com/ansible/awx-operator/blob/devel/README.md#basic-install) steps. - -Install some dependencies: - -``` -$ ansible-galaxy collection install -r molecule/requirements.yml -$ pip install -r molecule/requirements.txt -``` - -To prevent the changes we're about to make from being overwritten, scale down any running instance of the operator: - -``` -$ kubectl scale deployment awx-operator-controller-manager --replicas=0 -``` - -Create a playbook that invokes the installer role (the operator uses ansible-runner's role execution feature): - -```yaml -# run.yml ---- -- hosts: localhost - roles: - - installer -``` - -Create a vars file: - -```yaml -# vars.yml ---- -ansible_operator_meta: - name: awx - namespace: awx -service_type: nodeport -``` -The vars file will replace the awx resource so any value that you wish to over ride using the awx resource, put in the vars file. For example, if you wish to use your own image, version and pull policy, you can specify it like below: - -```yaml -# vars.yml ---- -ansible_operator_meta: - name: awx - namespace: awx -service_type: nodeport -image: $DEV_DOCKER_TAG_BASE/awx_kube_devel -image_pull_policy: Always -image_version: $COMPOSE_TAG -``` - -Run the installer: - -``` -$ ansible-playbook run.yml -e @vars.yml -v -``` - -Grab the URL and admin password: - -``` -$ minikube service awx-service --url -n awx -$ minikube kubectl get secret awx-admin-password -- -o jsonpath="{.data.password}" | base64 --decode -LU6lTfvnkjUvDwL240kXKy1sNhjakZmT -```