From bf3965eac7d526fbf3f77bf55d8d640d98d418ae 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 | 65 +++++++++++++-- docs/{ => migration}/migration.md | 0 .../advanced-configuration/migration.md | 82 ------------------- docs/user-guide/database-configuration.md | 2 +- 4 files changed, 59 insertions(+), 90 deletions(-) rename docs/{ => migration}/migration.md (100%) delete mode 100644 docs/user-guide/advanced-configuration/migration.md diff --git a/README.md b/README.md index d02a7226..aa314379 100644 --- a/README.md +++ b/README.md @@ -12,18 +12,20 @@ An [Ansible AWX](https://github.com/ansible/awx) operator for Kubernetes built w -NOTE: we are in the process of moving this readme into official docs in the /docs folder. Please go there to find additional sections during this interim move phase. +**Note**: We are in the process of moving this readme into official docs in the /docs folder. Please go there to find additional sections during this interim move phase. Table of Contents ================= -* [AWX Operator](#awx-operator) - * [Contributing](#contributing) - * [Release Process](#release-process) - * [Author](#author) - * [Code of Conduct](#code-of-conduct) - * [Get Involved](#get-involved) +- [AWX Operator](#awx-operator) +- [Table of Contents](#table-of-contents) + - [Install and Configuration](#install-and-configuration) + - [Contributing](#contributing) + - [Release Process](#release-process) + - [Author](#author) + - [Code of Conduct](#code-of-conduct) + - [Get Involved](#get-involved) @@ -31,6 +33,55 @@ Table of Contents +## Install and Configuration + +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) +- 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) +- Installation + - [Basic Install](./docs/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) +- 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) + - 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) +- Troubleshooting + - [General Debugging](./docs/debugging.md) + + ## Contributing Please visit [our contributing guidelines](https://github.com/ansible/awx-operator/blob/devel/CONTRIBUTING.md). diff --git a/docs/migration.md b/docs/migration/migration.md similarity index 100% rename from docs/migration.md rename to docs/migration/migration.md diff --git a/docs/user-guide/advanced-configuration/migration.md b/docs/user-guide/advanced-configuration/migration.md deleted file mode 100644 index f0d5f7c8..00000000 --- a/docs/user-guide/advanced-configuration/migration.md +++ /dev/null @@ -1,82 +0,0 @@ -# Migrating data from an old AWX instance - -To migrate data from an older AWX installation, you must provide some information via Secrets. - -## Creating Secrets for Migration - -### Secret Key - -You can find your old secret key in the inventory file you used to deploy AWX in releases prior to version 18. - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: -secret-key - namespace: -stringData: - secret_key: -type: Opaque -``` - -**Note**: `` must match the `name` of the AWX object you are creating. In our example below, it is `awx`. - -### Old Database Credentials - -The secret should be formatted as follows: - -```yaml ---- -apiVersion: v1 -kind: Secret -metadata: - name: -old-postgres-configuration - namespace: -stringData: - host: - port: "" # quotes are required - database: - username: - password: -type: Opaque -``` - -> For `host`, a URL resolvable by the cluster could look something like `postgresql..svc.cluster.local`, where `` is filled in with the namespace of the AWX deployment you are migrating data from. - -If your AWX deployment is already using an external database server or its database is otherwise not managed -by the AWX deployment, you can instead create the same secret as above but omit the `-old-` from the `name`. -In the next section pass it in through `postgres_configuration_secret` instead, omitting the `_old_` -from the key and ensuring the value matches the name of the secret. This will make AWX pick up on the existing -database and apply any pending migrations. It is strongly recommended to backup your database beforehand. - -The postgresql pod for the old deployment is used when streaming data to the new postgresql pod. If your postgresql pod has a custom label, -you can pass that via the `postgres_label_selector` variable to make sure the postgresql pod can be found. - -## Deploy AWX - -When you apply your AWX object, you must specify the name to the database secret you created above: - -```yaml -apiVersion: awx.ansible.com/v1beta1 -kind: AWX -metadata: - name: awx -spec: - old_postgres_configuration_secret: -old-postgres-configuration - secret_key_secret: -secret-key - ... -``` -## Important Note -If you intend to put all the above in one file, make sure to separate each block with three dashes like so: - -```yaml ---- -# Secret key - ---- -# Database creds - ---- -# AWX Config -``` -Failing to do so will lead to an inoperable setup. diff --git a/docs/user-guide/database-configuration.md b/docs/user-guide/database-configuration.md index d76669c1..fdf98145 100644 --- a/docs/user-guide/database-configuration.md +++ b/docs/user-guide/database-configuration.md @@ -48,7 +48,7 @@ spec: #### Migrating data from an old AWX instance -For instructions on how to migrate from an older version of AWX, see [migration.md](/docs/user-guide/advanced-configuration/migration.md). +For instructions on how to migrate from an older version of AWX, see [migration.md](/docs/migration/migration.md). #### Managed PostgreSQL Service