From 3929fb7c2764a85257361826d6658017109ccbe9 Mon Sep 17 00:00:00 2001 From: David Parker Date: Thu, 21 May 2026 00:48:54 +0100 Subject: [PATCH] [patch] Unify the documentation --- .bob/plans/2026-05-20-docs-reorganization.md | 87 ++ .bob/redis-locking/README.md | 1 + .../ibm-toolchain-redis-setup.sh | 0 .../redis-locking}/redis-locking-setup.md | 0 .secrets.baseline | 46 +- Makefile | 13 +- docs/catalogs/index.md | 2 +- docs/commands/configure-airgap.md | 20 - docs/commands/provision-aws.md | 11 - docs/commands/provision-fyre.md | 51 -- docs/commands/provision-roks.md | 46 -- docs/commands/provision-rosa.md | 11 - docs/commands/setup-registry.md | 39 - docs/commands/teardown-registry.md | 37 - docs/commands/uninstall.md | 46 -- docs/guides/aiservice-install.md | 8 +- docs/guides/backup.md | 752 ++++++++++++++++++ docs/guides/configure-airgap.md | 400 ++++++++++ docs/guides/install.md | 28 +- docs/guides/private-registry.md | 246 ++++++ docs/guides/provision-aws.md | 31 + docs/guides/provision-fyre.md | 357 +++++++++ docs/guides/provision-roks.md | 194 +++++ docs/guides/restore.md | 651 +++++++++++++++ docs/guides/uninstall.md | 98 ++- docs/index.md | 38 +- mkdocs.yml | 51 +- 27 files changed, 2919 insertions(+), 345 deletions(-) create mode 100644 .bob/plans/2026-05-20-docs-reorganization.md create mode 100644 .bob/redis-locking/README.md rename {docs => .bob/redis-locking}/ibm-toolchain-redis-setup.sh (100%) mode change 100755 => 100644 rename {docs => .bob/redis-locking}/redis-locking-setup.md (100%) delete mode 100644 docs/commands/configure-airgap.md delete mode 100644 docs/commands/provision-aws.md delete mode 100644 docs/commands/provision-fyre.md delete mode 100644 docs/commands/provision-roks.md delete mode 100644 docs/commands/provision-rosa.md delete mode 100644 docs/commands/setup-registry.md delete mode 100644 docs/commands/teardown-registry.md delete mode 100644 docs/commands/uninstall.md create mode 100644 docs/guides/backup.md create mode 100644 docs/guides/configure-airgap.md create mode 100644 docs/guides/private-registry.md create mode 100644 docs/guides/provision-aws.md create mode 100644 docs/guides/provision-fyre.md create mode 100644 docs/guides/provision-roks.md create mode 100644 docs/guides/restore.md diff --git a/.bob/plans/2026-05-20-docs-reorganization.md b/.bob/plans/2026-05-20-docs-reorganization.md new file mode 100644 index 00000000000..20ff6965353 --- /dev/null +++ b/.bob/plans/2026-05-20-docs-reorganization.md @@ -0,0 +1,87 @@ +# Documentation Reorganization Plan + +## Objective + +Consolidate all documentation from `docs/commands/` into `docs/guides/`, ensuring each CLI function has a comprehensive guide. Review all documents for quality, consistency, and style using `docs/guides/install.md` as the exemplar. Split the existing backup-restore guide into separate backup and restore documents. + +## Critical Rules + +1. **Use install.md as the style exemplar** - All documents must follow the structure, formatting, and tone of `docs/guides/install.md` +2. **One page at a time** - Complete each document fully before moving to the next +3. **Configure redirects** - Add redirect mappings in `mkdocs.yml` for all moved/renamed pages +4. **Preserve content** - Do not delete information; reorganize and improve it +5. **Validate after each change** - Ensure mkdocs builds successfully after each document update + +## Execution Plan + +### Phase 1: Split Backup-Restore Guide + +- [ ] **1.1** Create `docs/guides/backup.md` from backup-restore.md content +- [ ] **1.2** Create `docs/guides/restore.md` from backup-restore.md content +- [ ] **1.3** Update mkdocs.yml navigation and add redirects +- [ ] **1.4** Delete obsolete backup-restore.md and command files +- [ ] **1.5** Validate Phase 1 + +### Phase 2: Migrate Must-Gather Command + +- [ ] **2.1** Create comprehensive `docs/guides/must-gather.md` +- [ ] **2.2** Update mkdocs.yml with navigation and redirect +- [ ] **2.3** Delete `docs/commands/must-gather.md` +- [ ] **2.4** Validate Phase 2 + +### Phase 3: Migrate Airgap Configuration + +- [ ] **3.1** Create comprehensive `docs/guides/configure-airgap.md` +- [ ] **3.2** Update mkdocs.yml with navigation and redirect +- [ ] **3.3** Delete `docs/commands/configure-airgap.md` +- [ ] **3.4** Validate Phase 3 + +### Phase 4: Migrate Registry Commands + +- [ ] **4.1** Create `docs/guides/setup-registry.md` +- [ ] **4.2** Create `docs/guides/teardown-registry.md` +- [ ] **4.3** Update mkdocs.yml with navigation and redirects +- [ ] **4.4** Delete obsolete command files +- [ ] **4.5** Validate Phase 4 + +### Phase 5: Migrate Provisioning Commands ✅ COMPLETED + +- [x] **5.1** Create `docs/guides/provision-fyre.md` +- [x] **5.2** Create `docs/guides/provision-roks.md` +- [x] **5.3** Create `docs/guides/provision-rosa.md` +- [x] **5.4** Create `docs/guides/provision-aws.md` +- [x] **5.5** Update mkdocs.yml with navigation and redirects +- [x] **5.6** Delete obsolete provisioning command files +- [x] **5.7** Validate Phase 5 - mkdocs serving successfully + +### Phase 6: Migrate Remaining Commands + +- [ ] **6.1** Create `docs/guides/mirror-redhat-images.md` +- [ ] **6.2** Create `docs/guides/configtool-oidc.md` +- [ ] **6.3** Create `docs/guides/debug.md` if needed +- [ ] **6.4** Update mkdocs.yml and remove Command Reference section +- [ ] **6.5** Delete all remaining command files +- [ ] **6.6** Validate Phase 6 + +### Phase 7: Review Existing Guides + +- [ ] **7.1** Review `docs/guides/install.md` +- [ ] **7.2** Review `docs/guides/update.md` +- [ ] **7.3** Review `docs/guides/upgrade.md` +- [ ] **7.4** Review `docs/guides/uninstall.md` +- [ ] **7.5** Review `docs/guides/aiservice-install.md` +- [ ] **7.6** Review `docs/guides/image-mirroring.md` +- [ ] **7.7** Review `docs/guides/image-validation.md` +- [ ] **7.8** Validate Phase 7 + +### Phase 8: Final Cleanup + +- [ ] **8.1** Verify docs/commands directory is empty or removed +- [ ] **8.2** Review all redirects in mkdocs.yml +- [ ] **8.3** Review navigation structure +- [ ] **8.4** Build and test documentation +- [ ] **8.5** Create summary of changes + +## Validation + +After each phase run `mkdocs serve` and verify builds, navigation, and redirects work correctly. \ No newline at end of file diff --git a/.bob/redis-locking/README.md b/.bob/redis-locking/README.md new file mode 100644 index 00000000000..7feccd01d22 --- /dev/null +++ b/.bob/redis-locking/README.md @@ -0,0 +1 @@ +These documents had been generated in `/docs` but were and are not part of the documentation site - I don't know if they are even needed or not, if they are needed they need a proper home - which is probably not even this repository given the role of the script? diff --git a/docs/ibm-toolchain-redis-setup.sh b/.bob/redis-locking/ibm-toolchain-redis-setup.sh old mode 100755 new mode 100644 similarity index 100% rename from docs/ibm-toolchain-redis-setup.sh rename to .bob/redis-locking/ibm-toolchain-redis-setup.sh diff --git a/docs/redis-locking-setup.md b/.bob/redis-locking/redis-locking-setup.md similarity index 100% rename from docs/redis-locking-setup.md rename to .bob/redis-locking/redis-locking-setup.md diff --git a/.secrets.baseline b/.secrets.baseline index 636562b69f4..d609ed18005 100644 --- a/.secrets.baseline +++ b/.secrets.baseline @@ -3,7 +3,7 @@ "files": "build/bin/config/oscap/ssg-rhel9-ds.xml|^.secrets.baseline$|^docs/catalogs/", "lines": null }, - "generated_at": "2026-05-19T12:05:11Z", + "generated_at": "2026-05-20T23:47:35Z", "plugins_used": [ { "name": "AWSKeyDetector" @@ -87,52 +87,70 @@ "verified_result": null } ], - "docs/commands/provision-fyre.md": [ + "docs/guides/configure-airgap.md": [ { - "hashed_secret": "b60d121b438a380c343d5ec3c2037564b82ffef3", + "hashed_secret": "354b3a4b7715d3694c88a4fa7db49e41de86568e", "is_secret": false, "is_verified": false, - "line_number": 44, + "line_number": 145, "type": "Secret Keyword", "verified_result": null } ], - "docs/commands/provision-roks.md": [ + "docs/guides/image-mirroring.md": [ { "hashed_secret": "b60d121b438a380c343d5ec3c2037564b82ffef3", "is_secret": false, "is_verified": false, - "line_number": 40, + "line_number": 46, "type": "Secret Keyword", "verified_result": null } ], - "docs/commands/setup-registry.md": [ + "docs/guides/install.md": [ { "hashed_secret": "b60d121b438a380c343d5ec3c2037564b82ffef3", "is_secret": false, "is_verified": false, - "line_number": 31, + "line_number": 353, "type": "Secret Keyword", "verified_result": null } ], - "docs/guides/image-mirroring.md": [ + "docs/guides/private-registry.md": [ { - "hashed_secret": "b60d121b438a380c343d5ec3c2037564b82ffef3", + "hashed_secret": "354b3a4b7715d3694c88a4fa7db49e41de86568e", "is_secret": false, "is_verified": false, - "line_number": 46, + "line_number": 122, "type": "Secret Keyword", "verified_result": null } ], - "docs/guides/install.md": [ + "docs/guides/provision-fyre.md": [ { - "hashed_secret": "b60d121b438a380c343d5ec3c2037564b82ffef3", + "hashed_secret": "11fa7c37d697f30e6aee828b4426a10f83ab2380", + "is_secret": false, + "is_verified": false, + "line_number": 107, + "type": "Secret Keyword", + "verified_result": null + }, + { + "hashed_secret": "c7f112c59ab7e077fd20a28107b7a200469ebdac", + "is_secret": false, + "is_verified": false, + "line_number": 252, + "type": "Secret Keyword", + "verified_result": null + } + ], + "docs/guides/provision-roks.md": [ + { + "hashed_secret": "11fa7c37d697f30e6aee828b4426a10f83ab2380", "is_secret": false, "is_verified": false, - "line_number": 361, + "line_number": 95, "type": "Secret Keyword", "verified_result": null } diff --git a/Makefile b/Makefile index 43e8249ef62..6a6565f6c24 100644 --- a/Makefile +++ b/Makefile @@ -259,6 +259,17 @@ detect-secrets: detect-secrets scan --update .secrets.baseline detect-secrets audit .secrets.baseline + +.venv-docs: +# We need to install the python-devops and cli packages because we generate documentation from their code using mkdocs directives + python3 -m venv .venv-docs + . .venv-docs/bin/activate && python -m pip install setuptools + . .venv-docs/bin/activate && python -m pip install -e ../python-devops + . .venv-docs/bin/activate && python -m pip install -e ./python +# Install mkdocs and the various plugins that we use, including our custom plugins + . .venv-docs/bin/activate && python -m pip install -q mkdocs properdocs mkdocs-carbon mkdocs-glightbox mkdocs-redirects + . .venv-docs/bin/activate && python -m pip install -e ./mkdocs_plugins + .PHONY: mkdocs-serve -mkdocs-serve: +mkdocs-serve: .venv-docs . .venv-docs/bin/activate && mkdocs serve --livereload --dev-addr localhost:9010 diff --git a/docs/catalogs/index.md b/docs/catalogs/index.md index 964fb7c0065..e26e3780a99 100644 --- a/docs/catalogs/index.md +++ b/docs/catalogs/index.md @@ -521,7 +521,7 @@ The packages available in these catalogs are fixed. Multiple installations at di #### Disconnected Install > I want to run a disconnected environment using a private mirror registry -The MAS CLI [mirror-images](../guides/image-mirroring.md) function is the easiest way to mirror the content from a specific version of the Maximo Operator Catalog. Once the images are mirrored simply run the [configure-airgap](../commands/configure-airgap.md) function to add the IBM Maximo Application Suite **ImageDigestMirrorset** to your cluster before starting the installation. +The MAS CLI [mirror-images](../guides/image-mirroring.md) function is the easiest way to mirror the content from a specific version of the Maximo Operator Catalog. Once the images are mirrored simply run the [configure-airgap](../guides/configure-airgap.md) function to add the IBM Maximo Application Suite **ImageDigestMirrorset** to your cluster before starting the installation. ### Dynamic Catalog diff --git a/docs/commands/configure-airgap.md b/docs/commands/configure-airgap.md deleted file mode 100644 index ba9418e06f3..00000000000 --- a/docs/commands/configure-airgap.md +++ /dev/null @@ -1,20 +0,0 @@ -# Configure Airgap - -!!! important - The `configure-airgap` command does not work on **IBMCloud ROKS** clusters. This is a limitation of the service provided in IBMCloud which disables key parts of OpenShift functionality required to configure and use ImageContentSourcePolicy resources (which is the basis of airgap/image mirroring support in OpenShift). - - -## Usage - -### Interactive -```bash -docker run -ti --rm -v ~:/mnt/local --pull always quay.io/ibmmas/cli mas configure-airgap -``` - -### Non-Interactive -```bash -docker run -ti --rm -v ~:/mnt/local --pull always quay.io/ibmmas/cli mas configure-airgap \ - -H myprivateregistry.com -P 5000 -u $REGISTRY_USERNAME -p $REGISTRY_PASSWORD \ - --ca-file /mnt/local/registry-ca.crt \ - --no-confirm -``` diff --git a/docs/commands/provision-aws.md b/docs/commands/provision-aws.md deleted file mode 100644 index c4155f3fbfb..00000000000 --- a/docs/commands/provision-aws.md +++ /dev/null @@ -1,11 +0,0 @@ -Provision OCP on AWS SNO -=============================================================================== - -Usage -------------------------------------------------------------------------------- - -### Non-Interactive Mode - -```bash -docker run -ti --rm --pull always quay.io/ibmmas/cli mas provision-aws -``` diff --git a/docs/commands/provision-fyre.md b/docs/commands/provision-fyre.md deleted file mode 100644 index 8e7df1211dd..00000000000 --- a/docs/commands/provision-fyre.md +++ /dev/null @@ -1,51 +0,0 @@ -Provision OCP on FYRE -=============================================================================== - -Usage -------------------------------------------------------------------------------- -`mas provision-fyre [options]` - -### FYRE Credentials -- `-u|--username FYRE_USERNAME` FYRE username -- `-a|--apikey FYRE_APIKEY` FYRE API key - -### Cluster Configuration -- `-p|--product-id FYRE_PRODUCT_ID` FYRE product group ID that will own the cluster -- `-q|--quota-type FYRE_QUOTA_TYPE` Declare the quota to use when provisioning the cluster ("quick_burn" or "product_group") -- `-c|--cluster-name CLUSTER_NAME` Name of the cluster to be provisioned (lowercase only) -- `-v|--ocp-version OCP_VERSION` OCP version to use (e.g 4.13, 4.14) -- `-d|--description FYRE_DESCRIPTION` Description of the OCP cluster - -### Worker Node Configuration -- `--worker-count FYRE_WORKER_COUNT` Number of worker nodes to provision -- `--worker-cpu FYRE_WORKER_CPU` How many CPUs to allocate per worker node -- `--worker-memory FYRE_WORKER_MEMORY` How much memory to allocate per worker node -- `--worker-additional-disks FYRE_WORKER_ADDITIONAL_DISKS` Comma-seperated list of additional disks (in Gb) added to each worker node (e.g. "200,200") -- `--fyre-cluster-size FYRE_CLUSTER_SIZE` When Fyre Quick Burn, defines the size category ("medium" or "large") - -### Storage Provisioner Configuration -- `--storage` Configure the storage provider (nfs, odf, or longhorn) -- `--nfs-image-registry-size FYRE_NFS_IMAGE_REGISTRY_SIZE` Defines the image registry storage size when configured to use NFS (default 100gb). The size allocated cannot be superior of storage available in the Fyre Infrastructure node. - -### Other Commands -- `--no-confirm` Provision the cluster without prompting for confirmation -- `-h|--help` Show this help message - -Examples -------------------------------------------------------------------------------- -### Interactive Mode -```bash -docker run -ti --rm --pull always quay.io/ibmmas/cli mas provision-fyre -``` - -### Non-Interactive Mode -```bash -export FYRE_USERNAME=xxx -export FYRE_APIKEY=xxx -docker run -ti --rm --pull always quay.io/ibmmas/cli mas provision-fyre \ - -u $FYRE_USERNAME -a $FYRE_APIKEY \ - -p 225 -q product_group \ - -c masonfyre -d "My Cluster" -v 4.15 \ - --worker-count 3 --worker-cpu 8 --worker-memory 32 \ - --no-confirm -``` diff --git a/docs/commands/provision-roks.md b/docs/commands/provision-roks.md deleted file mode 100644 index fdc0cd1ec85..00000000000 --- a/docs/commands/provision-roks.md +++ /dev/null @@ -1,46 +0,0 @@ -Provision OCP on IBMCloud ROKS -=============================================================================== - -Usage -------------------------------------------------------------------------------- -`mas provision-roks [options]` - -### IBMCloud Credentials -- `-a|--apikey IBMCLOUD_APIKEY` IBMCloud API key - -### Cluster Configuration -- `-r|--resource-group IBMCLOUD_RESOURCEGROUP` IBMCloud resource group to deploy the cluster in -- `-c|--cluster-name CLUSTER_NAME` Name of the cluster to be provisioned -- `-v|--ocp-version OCP_VERSION` OCP version to use (e.g 4.13_openshift, 4.14_openshift) - -### Worker Node Configuration -- `--worker-count ROKS_WORKERS` Number of worker nodes to provision -- `--worker-flavor ROKS_FLAVOR` The flavour of worker node to use (e.g. b3c.16x64.300gb) -- `--worker-zone ROKS_ZONE` IBM Cloud zone where the cluster should be provisioned. (e.g. dal10) - -### GPU Support -- `--gpu-worker-count GPU_WORKERS` Number of GPU worker nodes to provision -- `--gpu-workerpool-name GPU_WORKERPOOL_NAME` Name of the GPU workerpool - -### Other Commands -- `--no-confirm` Provision the cluster without prompting for confirmation -- `-h|--help` Show help message - - -Examples -------------------------------------------------------------------------------- - -### Interactive Mode -```bash -docker run -ti --rm --pull always quay.io/ibmmas/cli mas provision-roks -``` - -### Non-Interactive Mode -```bash -export IBMCLOUD_APIKEY=xxx -docker run -ti --rm --pull always quay.io/ibmmas/cli mas provision-roks \ - -a $IBMCLOUD_APIKEY -r mas-development \ - -c masonroks -v 4.15_openshift \ - --worker-count 3 --worker-flavor b3c.16x64.300gb --worker-zone dal10 \ - --no-confirm -``` diff --git a/docs/commands/provision-rosa.md b/docs/commands/provision-rosa.md deleted file mode 100644 index c578f8a850d..00000000000 --- a/docs/commands/provision-rosa.md +++ /dev/null @@ -1,11 +0,0 @@ -Provision OCP on AWS ROSA -=============================================================================== - -Usage -------------------------------------------------------------------------------- - -### Non-Interactive Mode - -```bash -docker run -ti --rm --pull always quay.io/ibmmas/cli mas provision-rosa -``` diff --git a/docs/commands/setup-registry.md b/docs/commands/setup-registry.md deleted file mode 100644 index a3a5af69ca1..00000000000 --- a/docs/commands/setup-registry.md +++ /dev/null @@ -1,39 +0,0 @@ -Setup Private Registry -=============================================================================== - -Usage -------------------------------------------------------------------------------- -`mas setup-registry [options]` - -### Registry Credentials (required) -- `-u|--username` Registry username -- `-p|--password` Registry password - -### Registry Cluster Configuration (optional) -- `-n|--namespace` Registry namespace (default is airgap-registry) -- `-s|--storage-class` Registry storage class (default is ibmc-block-gold) -- `-c|--storage-capacity` Registry storage capacity (default is 2000Gi) -- `-t|--service-type` Registry service type (default is loadbalancer) - -### Other Commands: -- `-h|--help` Show help message - -Examples -------------------------------------------------------------------------------- - -### Interactive Mode -```bash -docker run -ti --rm --pull always quay.io/ibmmas/cli mas setup-registry -``` - -### Non-Interactive Mode -```bash -export REGISTRY_PASSWORD=xxx -docker run -ti --rm --pull always quay.io/ibmmas/cli mas setup-registry \ - -u my-registry-user \ - -p $REGISTRY_PASSWORD \ - -n airgap -s nfs-client \ - --service-type loadbalancer \ - --storage-capacity 2000Gi \ - --no-confirm -``` \ No newline at end of file diff --git a/docs/commands/teardown-registry.md b/docs/commands/teardown-registry.md deleted file mode 100644 index b6f31c20c5d..00000000000 --- a/docs/commands/teardown-registry.md +++ /dev/null @@ -1,37 +0,0 @@ -Tear Down Private Registry -=============================================================================== -This function is used to delete a private/mirror registry from a given cluster to enable a clean start. - -Usage -------------------------------------------------------------------------------- -Note that using the `teardown-registry` command will delete the registry completely including the PVC storage and the registry namespace. The registry will need to be recreated after running this command if desired. To start up the registry again, run the `setup-registry`command. Images previously stored in the registry before the teardown will no longer be available and will need to be mirrored again once the registry setup has completed. Take precaution when using this function and expect that images can no longer be accessed from the registry that is being torn down. - -**IMPORTANT:** The `teardown-registry` command permanently deletes all registry data. - -An appropriate time to use this tear-down function is when the registry has too many images that are not being used or when there has been a shift to support newer versions but images of older versions are clogging the registry. The tear-down function frees the disk space and allows for a new registry to be setup. - -**Note:** Recreating the registry will create a new ca cert for the new registry. - -`mas setup-registry [options]` - -### Registry Cluster Configuration (optional) -- `-n|--namespace` Registry namespace (default is airgap-registry) - -### Other Commands: -- `-h|--help` Show help message - -Examples -------------------------------------------------------------------------------- - -### Interactive Mode -```bash -docker run -ti --rm --pull always quay.io/ibmmas/cli mas teardown-registry -``` - -### Non-Interactive Mode -```bash -docker run -ti --rm --pull always quay.io/ibmmas/cli mas teardown-registry \ - -n airgap \ - --no-confirm -``` - diff --git a/docs/commands/uninstall.md b/docs/commands/uninstall.md deleted file mode 100644 index cae59e66e85..00000000000 --- a/docs/commands/uninstall.md +++ /dev/null @@ -1,46 +0,0 @@ -Uninstall -=============================================================================== - -Usage -------------------------------------------------------------------------------- -Usage information can be obtained using `mas uninstall --help` - -``` -usage: mas uninstall [--mas-instance-id MAS_INSTANCE_ID] [--uninstall-all-deps] [--uninstall-cert-manager] [--uninstall-common-services] [--uninstall-grafana] - [--uninstall-ibm-catalog] [--uninstall-mongodb] [--uninstall-sls] [--uninstall-dro] [--no-confirm] [-h] - -IBM Maximo Application Suite Admin CLI v100.0.0 -Uninstall MAS by configuring and launching the MAS Uninstall Tekton Pipeline. - -Interactive Mode: -Omitting the --instance-id option will trigger an interactive prompt - -MAS Instance Selection: - --mas-instance-id MAS_INSTANCE_ID The MAS instance ID to be uninstalled - -MAS Dependencies Selection: - --uninstall-all-deps Uninstall all MAS-related dependencies from the target cluster - --uninstall-cert-manager Uninstall Certificate Manager from the target cluster - --uninstall-common-services Uninstall IBM Common Services from the target cluster - --uninstall-grafana Uninstall Grafana from the target cluster - --uninstall-ibm-catalog Uninstall the IBM Maximo Operator Catalog Source (ibm-operator-catalog) from the target cluster - --uninstall-mongodb Uninstall MongoDb from the target cluster - --uninstall-sls Uninstall IBM Suite License Service from the target cluster - --uninstall-dro Uninstall IBM Data Reporter from the target cluster - -More: - --no-confirm Launch the upgrade without prompting for confirmation - -h, --help Show this help message and exit -``` - -Examples -------------------------------------------------------------------------------- -### Interactive Uninstall -```bash -mas uninstall -``` - -### Non-Interactive Uninstall -```bash -mas uninstall --mas-instance-id inst1 --no-confirm -``` diff --git a/docs/guides/aiservice-install.md b/docs/guides/aiservice-install.md index bc6940ef211..89ab50eb86c 100644 --- a/docs/guides/aiservice-install.md +++ b/docs/guides/aiservice-install.md @@ -36,9 +36,9 @@ You should already have a target OpenShift cluster ready to install AI Service i The CLI also supports OpenShift provisioning in many hyperscaler providers: -- [AWS](../commands/provision-rosa.md) -- [IBM Cloud](../commands/provision-roks.md) -- [IBM DevIT FYRE (Internal)](../commands/provision-fyre.md) +- [AWS](provision-aws.md) +- [IBM Cloud](provision-roks.md) +- [IBM DevIT FYRE (Internal)](provision-fyre.md) ### Operator Catalog Selection If you have not already determined the catalog version for your installation, refer to the information in the [Operator Catalog](../catalogs/index.md) topic, or contact IBM Support for guidance. @@ -375,4 +375,4 @@ When installing Manage alongside AI Service using `mas install`: You can configure the AI Service binding through the Maximo Manage UI. -For more information on integrating AI Service with Manage, see the [Installation Guide](install.md#application-configuration). \ No newline at end of file +For more information on integrating AI Service with Manage, see the [Installation Guide](install.md). \ No newline at end of file diff --git a/docs/guides/backup.md b/docs/guides/backup.md new file mode 100644 index 00000000000..b98afb7fb6d --- /dev/null +++ b/docs/guides/backup.md @@ -0,0 +1,752 @@ +# Backup +The MAS backup process uses Tekton pipelines to orchestrate the backup of multiple components. The Tekton pipeline executes [Ansible DevOps Collection](https://ibm-mas.github.io/ansible-devops/) roles to perform the actual backup operations. + +!!! warning + Before you begin + + Be aware of the following versioning considerations for the MAS CLI releases: + + The MAS backup and restore in CLI release v19.0.0 and later contains process, backup archive file and directory changes that are not backward compatible with earlier backup and restore versions. + + Run the backup processes using v19.0.0 or later to ensure that you can successfully run a restore. You cannot run a restore process using v19.0.0 or later from back ups created on an older version. + +**Supported MAS versions** + +- MAS 9.1.x + +Note: MAS 9.0.x (Not supported yet, its in testing) + +**User Permissions Required** + +- `oc` CLI with cluster admin permissions +- `mas` CLI with appropriate permissions +- Access to Tekton pipeline resources + + +Backup Overview +------------------------------------------------------------------------------- +### Backup Components + +- **IBM Operator Catalogs** - Catalog source definitions +- **Certificate Manager** - Certificate configurations (RedHat only) +- **MongoDB** - MAS configuration database (Community Edition only) +- **Suite License Service (SLS)** - License server data (optional) +- **MAS Suite Configuration** - Core MAS instance configuration and custom resources +- **MAS Applications** - Application-specific resources and persistent volume data (optional) +- **Db2 Database** - Db2 instance resources and database backups (optional) + +The backup creates a compressed archive for each supported component that can be stored locally or uploaded to cloud storage (S3 or Artifactory). + +### Backup Limitations + +!!! warning + Be aware of the following limitations before performing a backup: + +- **MongoDB Community Edition only** - The backup process supports only in-cluster MongoDB Community Edition. External or enterprise MongoDB deployments are not backed up. +- **Db2 standalone operator only** - The backup process supports only the in-cluster standalone Db2 operator. Other Db2 operator implementations are not included. +- **Certificate Manager (RedHat only)** - Certificate Manager backup is supported only for RedHat Certificate Manager. Other certificate manager implementations are not included. +- **No support for some apps** - Only Manage application is supported for now. Other MAS applications (Facilities, Monitor, IoT, Predict, etc.) are not supported, but will be added in later releases. +- **No OpenShift cluster state** - The backup does not capture the full OpenShift cluster state, node configurations, or cluster-level resources outside of MAS namespaces. +- **No IBM Cloud Pak for Data backups** - The backup process does not support backing up CP4D itself. +- **No Incremental backups** - Each backup is a full backup; incremental or differential backups are not supported. +- **Single MAS instance per backup** - Each backup operation targets a single MAS instance. Multi-instance environments require separate backup runs per instance. +- **Tekton pipeline dependency** - The backup process requires Tekton pipelines to be available and functional on the cluster. +- **Storage class dependency** - Backup of Manage application's persistent volumes depends on the storage class supporting volume snapshots or the relevant backup mechanism. +- **S3/Artifactory upload is optional** - Without configuring cloud storage upload, backups are stored locally in the cluster and may be lost if the cluster is decommissioned. +- **Download backup archives to local machine manually** - The backup archives are stored in the cluster's pvc or uploaded to S3/Artifactory and must be downloaded to a local machine manually. + +!!! tip + We are working on reducing the limitations of the backup process and will be adding new capabilties and support for other MAS applications in future releases. + +### Ansible DevOps Integration + +The `mas backup` command launches a Tekton pipeline that executes the following Ansible roles from the [IBM MAS DevOps Collection](https://ibm-mas.github.io/ansible-devops/): + +- [`ibm.mas_devops.ibm_catalogs`](https://ibm-mas.github.io/ansible-devops/roles/ibm_catalogs/) - Backs up IBM Operator Catalog definitions +- [`ibm.mas_devops.cert_manager`](https://ibm-mas.github.io/ansible-devops/roles/cert_manager/) - Backs up Certificate Manager configurations +- [`ibm.mas_devops.mongodb`](https://ibm-mas.github.io/ansible-devops/roles/mongodb/) - Backs up MongoDB Community Edition instance and database +- [`ibm.mas_devops.sls`](https://ibm-mas.github.io/ansible-devops/roles/sls/) - Backs up Suite License Service data +- [`ibm.mas_devops.suite_backup`](https://ibm-mas.github.io/ansible-devops/roles/suite_backup/) - Backs up MAS Core configuration +- [`ibm.mas_devops.db2`](https://ibm-mas.github.io/ansible-devops/roles/db2/) - Backs up DB2 resources and persistent volume data +- [`ibm.mas_devops.suite_app_backup`](https://ibm-mas.github.io/ansible-devops/roles/suite_app_backup/) - Backs up MAS application resources and persistent volume data + +For detailed information about the underlying Ansible automation, see the [Backup and Restore Playbook Documentation](https://ibm-mas.github.io/ansible-devops/playbooks/backup-restore/). + +!!! tip + Advanced users can use the Ansible roles directly for custom backup workflows. The CLI provides a managed, simplified interface to these roles with additional features like automatic pipeline setup and cloud upload capabilities. + +### Backup Artifacts + +Backups are stored in the pipeline namespace PVC at: + +- **Backup Directory**: `/workspace/backups` + +When S3/artifactory upload is enabled, the backup archives will be uploaded to the bucket/artifactory repo under `mas--backups` directory. + +**S3 Backup Archive Directory Structure:** + +``` +s3://bucket-name/ (or Artfactory - https://na.artifactory.swg-devops.com/artifactory/repo-name/) +├── mas--backups/ + ├── mas--backup--catalog.tar.gz + ├── mas--backup--certmanager.tar.gz + ├── mas--backup--db2u-manage.tar.gz + ├── mas--backup--mongoce.tar.gz + ├── mas--backup--sls.tar.gz + └── mas--backup--suite.tar.gz + ├── mas--backup--app-manage.tar.gz +``` + +Each backup archive follows the naming convention: `-backup--.tar.gz` + +**Archive Components:** + +| Archive | Description | +|---------|-------------| +| `catalog.tar.gz` | IBM Operator Catalog configurations | +| `certmanager.tar.gz` | Certificate Manager configurations | +| `mongoce.tar.gz` | MongoDB Community Edition database backup | +| `sls.tar.gz` | Suite License Service data (if included) | +| `suite.tar.gz` | MAS Core configuration and data | +| `db2u-manage.tar.gz` | Manage Db2 database backup (if included) | +| `app-manage.tar.gz` | Manage application configuration (if included) | + +When to Backup +------------------------------------------------------------------------------- + +### Regular Backup Schedule +Establish a regular backup schedule based on your organization's requirements: + +- **Before major upgrades** - Always backup before upgrading MAS or its dependencies +- **After configuration changes** - Backup after significant configuration modifications +- **Regular intervals** - Weekly or monthly backups for disaster recovery +- **Before cluster maintenance** - Backup before OpenShift cluster maintenance windows + +### Migration Scenarios +Backups are essential for: + +- **Cluster migration** - Moving MAS from one OpenShift cluster to another +- **Disaster recovery** - Recovering from cluster failures or data corruption +- **Environment cloning** - Creating test/dev environments from production backups +- **Version rollback** - Reverting to a previous configuration state + + +Component Selection +------------------------------------------------------------------------------- + +### Including SLS in Backups + +**Include SLS (`--include-sls` or default behavior)** when: + +- SLS is deployed **in-cluster** in the same OpenShift environment as MAS +- You are using the standard MAS installation with bundled SLS +- The SLS namespace is accessible from your backup environment +- You want a complete, self-contained backup for disaster recovery + +**Exclude SLS (`--exclude-sls`)** when: + +- SLS is deployed **externally** in a separate cluster or environment +- You are using a shared SLS instance across multiple MAS installations +- SLS is managed by a different team or organization +- The SLS namespace is not accessible from your backup environment +- You only need to backup MAS-specific configuration + +!!! note + The default behavior is to **include SLS** in backups. You must explicitly use `--exclude-sls` to skip SLS backup. + +### Data Reporter Operator (DRO) + +The Data Reporter Operator (DRO) is **not included in backup operations** as it is typically configured during restore or installation. DRO configuration is handled separately and can be: + +- **Installed during restore** - DRO will be installed when restoring from a backup when `--include-dro` is specified +- **Configured externally** - If using an external DRO instance, it should be configured independently +- **Skipped** - DRO installation can be skipped during restore if not required, use `--exclude-dro` to skip DRO installation + +!!! info + DRO backup and restore behavior is managed by the underlying [Ansible DevOps roles](https://ibm-mas.github.io/ansible-devops/playbooks/backup-restore/). The CLI backup command focuses on capturing MAS configuration and data, while DRO is handled during the restore process. + +### MongoDB Configuration + +The backup process supports **MongoDB Community Edition only**. By default, MongoDB is included in the backup. You can configure MongoDB settings or exclude it if using an external MongoDB provider. + +**Including MongoDB in Backup (Default)** + +When MongoDB is included, ensure you specify the correct MongoDB configuration: + +- **Namespace** - Where MongoDB is deployed (default: `mongoce`) +- **Instance Name** - MongoDB instance identifier (default: `mas-mongo-ce`) +- **Provider** - Must be `community` (only supported provider for backup) + +**Excluding MongoDB from Backup** + +If you are using an external MongoDB provider (such as IBM Cloud Databases for MongoDB or other hosted MongoDB services), you should exclude MongoDB from the backup: + +- Use `--exclude-mongo` flag in non-interactive mode +- In interactive mode, answer "No" when prompted to include MongoDB in backup + +!!! warning + IBM Cloud Databases for MongoDB and other external MongoDB providers are not supported by the backup process. You must use their native backup mechanisms. When using external MongoDB, always use `--exclude-mongo` to skip MongoDB backup. + +!!! tip + When excluding MongoDB from backup, you are responsible for backing up your MongoDB database using your provider's native backup tools. Ensure MongoDB backups are coordinated with MAS backups for consistency. + +### Certificate Manager + +Specify the certificate manager provider used in your environment: + +- **Red Hat Certificate Manager** (`--cert-manager-provider redhat`) - Default option, and the only supported provider. + +The backup captures certificate configurations but not the actual certificates, which are regenerated during restore. + +### MAS Application Backup + +The backup process supports backing up MAS application resources and persistent volume data. Currently supported: + +- **Manage Application** - Backs up Manage namespace resources and persistent volume data + +When backing up a Manage application, the following resources are included: + +**Namespace Resources**: +- `ManageApp` custom resource +- `ManageWorkspace` custom resource +- Encryption secrets (dynamically determined from ManageWorkspace CR) +- Certificates with `mas.ibm.com/instanceId` label +- Subscription and OperatorGroup +- IBM entitlement secret +- All referenced secrets (auto-discovered) + +**Persistent Volume Data** (if configured in ManageWorkspace CR): +- All persistent volumes defined in `spec.settings.deployment.persistentVolumes` +- Data backed up as compressed tar.gz archives +- Each PVC's mount path archived separately +- Common PVCs include JMS server data, custom fonts, and attachments + +!!! note + Application backup is optional and configured during the interactive backup process or via command-line parameters (`--backup-manage-app`, `--manage-workspace-id`). + +### Db2 Database Backup + +The backup process supports backing up Db2 databases used by MAS applications. When backing up a Db2 database, the following are included: + +**Db2 Instance Resources**: +- `Db2uCluster` custom resource +- Secrets (instance password, certificates, LDAP credentials) +- ConfigMaps +- Services and routes +- Operator subscription + +**Database Data**: +- Complete database backup (full backup) +- Stored in the backup archive alongside other components +- Supports both online and offline backup modes + +**Backup Types**: + +- **Online Backup** - Database remains accessible during backup; requires archive logging enabled +- **Offline Backup** - Database unavailable during backup; works with circular logging (default configuration) + +!!! warning + If your Db2 instance uses circular logging (the default configuration), you **must** use offline backup type. Online backups require archive logging to be enabled via `LOGARCHMETH1` and `LOGARCHMETH2` configuration. + +!!! note + Db2 backup is optional and configured during the interactive backup process or via command-line parameters (`--backup-manage-db`, `--manage-db2-namespace`, `--manage-db2-instance-name`, `--manage-db2-backup-type`). + + +Backup Modes +------------------------------------------------------------------------------- + +### Interactive Mode + +Interactive mode guides you through the backup process with prompts for all required configuration. This is the recommended approach for manual backups. + +```bash +docker run -ti --rm quay.io/ibmmas/cli mas backup +``` + +The interactive session will: + +1. Prompt for OpenShift cluster connection +2. Display detected MAS instances +3. Request backup storage size +4. Offer auto-generated or custom backup version +5. Configure optional upload to S3 or Artifactory + +### Non-Interactive Mode + +Non-interactive mode is ideal for automation, scheduled backups, and CI/CD pipelines. All required parameters must be provided via command-line arguments. + +```bash +docker run -ti --rm quay.io/ibmmas/cli mas backup \ + --instance-id inst1 \ + --no-confirm +``` + + +Backup Scenarios - Non-Interactive Mode +------------------------------------------------------------------------------- + +### Scenario 1: Standard In-Cluster Deployment + +**Environment:** +- MAS with all dependencies in a single OpenShift cluster +- MongoDB Community Edition +- In-cluster SLS +- Red Hat Certificate Manager + +**Backup Command:** +```bash +mas backup \ + --instance-id inst1 \ + --backup-storage-size 50Gi \ + --no-confirm +``` + +This uses all default values and includes SLS in the backup. + +### Scenario 2: External SLS Deployment + +**Environment:** +- MAS in OpenShift cluster +- MongoDB Community Edition in-cluster +- SLS deployed in separate cluster or external environment +- Red Hat Certificate Manager + +**Backup Command:** +```bash +mas backup \ + --instance-id inst1 \ + --backup-storage-size 30Gi \ + --exclude-sls \ + --no-confirm +``` + +Use `--exclude-sls` to skip backing up SLS when it's managed externally. + +### Scenario 3: Custom MongoDB Configuration and backup version + +**Environment:** +- MAS with custom MongoDB namespace +- Custom backup version desired +- Custom MongoDB instance name +- In-cluster SLS +- Red Hat Certificate Manager + +**Backup Command:** +```bash +mas backup \ + --instance-id inst1 \ + --backup-version prod-backup-$(date +%Y%m%d) \ + --backup-storage-size 50Gi \ + --mongodb-namespace my-mongodb \ + --mongodb-instance-name custom-mongo-instance \ + --mongodb-provider community \ + --no-confirm +``` + +### Scenario 4: External MongoDB Deployment + +**Environment:** +- MAS in OpenShift cluster +- MongoDB hosted externally (e.g., IBM Cloud Databases for MongoDB, MongoDB Atlas, or other managed service) +- In-cluster SLS +- Red Hat Certificate Manager + +**Backup Command:** +```bash +mas backup \ + --instance-id inst1 \ + --backup-storage-size 30Gi \ + --exclude-mongo \ + --no-confirm +``` + +Use `--exclude-mongo` to skip backing up MongoDB when it's managed externally. You must use your MongoDB provider's native backup mechanisms to back up the database separately. + +!!! important + When using external MongoDB, coordinate your MongoDB backups with MAS backups to ensure data consistency. Back up MongoDB before or immediately after the MAS backup completes. + +### Scenario 5: Backup with S3 Upload + +**Environment:** +- Standard MAS deployment +- Custom backup version desired +- Automatic upload to AWS S3 for off-site storage + +**Backup Command:** +```bash +mas backup \ + --instance-id inst1 \ + --backup-version prod-$(date +%Y%m%d-%H%M%S) \ + --backup-storage-size 50Gi \ + --upload-backup \ + --aws-access-key-id AKIAIOSFODNN7EXAMPLE \ #pragma: allowlist secret + --aws-secret-access-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY \ #pragma: allowlist secret + --s3-bucket-name mas-backups-prod \ + --s3-region us-east-1 \ + --no-confirm +``` + +!!! tip + Store AWS credentials securely using environment variables or secrets management systems rather than hardcoding them in scripts. + +### Scenario 6: Backup with Manage Application and Db2 Database + +**Environment:** +- Standard MAS deployment with Manage application +- Manage workspace with persistent volumes configured +- In-cluster Db2 database for Manage +- Need to backup application resources, PV data, and database + +**Backup Command:** +```bash +mas backup \ + --instance-id inst1 \ + --backup-storage-size 100Gi \ + --backup-manage-app \ + --manage-workspace-id masdev \ + --backup-manage-db \ + --manage-db2-namespace db2u \ + --manage-db2-instance-name mas-inst1-masdev-manage \ + --manage-db2-backup-type offline \ + --no-confirm +``` + +!!! tip + When backing up Manage with Db2, ensure sufficient backup storage (100Gi+ recommended) to accommodate application PV data and database backups. Use offline backup type if your Db2 instance uses the default circular logging configuration. + +### Scenario 7: Backup with Manage Application Only (External Db2) + +**Environment:** +- MAS deployment with Manage application +- External Db2 database (managed separately) +- Only need to backup application resources and PV data + +**Backup Command:** +```bash +mas backup \ + --instance-id inst1 \ + --backup-storage-size 50Gi \ + --backup-manage-app \ + --manage-workspace-id masdev \ + --no-confirm +``` + +!!! note + When using an external Db2 database, omit the `--backup-manage-db` flag. The database should be backed up separately using your organization's database backup procedures. + +### Scenario 8: Backup for Troubleshooting (No Cleanup) + +**Environment:** +- Backup for troubleshooting purposes +- Custom backup version desired +- Need to inspect workspace contents after backup +- Workspace cleanup disabled + +**Backup Command:** +```bash +mas backup \ + --instance-id inst1 \ + --backup-version debug-$(date +%Y%m%d-%H%M%S) \ + --backup-storage-size 50Gi \ + --no-clean-backup \ + --no-confirm +``` + +!!! note + Use `--no-clean-backup` when you need to inspect the backup workspace contents for troubleshooting. Remember to manually clean up the workspaces later to free up storage. + +### Scenario 9: Minimal Backup (Skip Pre-Check) + +**Environment:** +- Emergency backup scenario +- Custom backup version desired +- Skip pre-backup validation for speed, and when the cluster is not 100% healthy + +**Backup Command:** +```bash +mas backup \ + --instance-id inst1 \ + --backup-version emergency-$(date +%Y%m%d-%H%M%S) \ + --backup-storage-size 50Gi \ + --skip-pre-check \ + --no-confirm +``` + +!!! warning + Use `--skip-pre-check` only in emergency situations. Pre-backup checks validate cluster health and can prevent incomplete backups. + + +Storage Requirements +------------------------------------------------------------------------------- + +### Backup Storage Sizing + +The backup storage size depends on several factors: + +| Component | Typical Size | Notes | +|-----------|-------------|-------| +| MAS Configuration | < 1 MB | Core MAS custom resources and configurations | +| MongoDB Database | 0.05-20 GB | Varies based on MAS app count and data volume | +| SLS Data | < 1 MB | License server database and configuration | +| IBM Catalogs | < 1 MB | Operator catalog definitions | +| Certificate Manager | < 1 MB | Certificate configurations | +| Manage App Resources | < 10 MB | Manage namespace Kubernetes resources | +| Manage PV Data | 1-100 GB | JMS server, fonts, attachments (if configured) | +| Db2 Instance Resources | < 10 MB | Db2 Kubernetes resources and metadata | +| Db2 Database Backup | Varies | 0.5-2x database size when compressed; depends on data volume | + +!!! tip + Monitor your first backup to determine actual storage requirements, then adjust the `--backup-storage-size` parameter for future backups. When backing up Manage with Db2, plan for significantly larger storage requirements (100GB+ recommended). + +### Storage Class Considerations + +The backup process automatically selects appropriate storage: + +- **Single Node OpenShift (SNO)**: Uses ReadWriteOnce (RWO) storage +- **Multi-node clusters**: Prefers ReadWriteMany (RWX) storage when available +- Falls back to RWO if RWX is not available + +The storage class is determined from your cluster's storage classes. + +You can override the default storage configuration using: + +- `--backup-storage-class`: Specify a custom storage class for the backup PVC +- `--backup-storage-access-mode`: Specify the access mode (e.g., ReadWriteOnce, ReadWriteMany) for the backup PVC + + +Backup Process Details +------------------------------------------------------------------------------- + +### Pipeline Execution + +When you run `mas backup`, the following occurs: + +1. **Validation** - Verifies cluster connectivity and MAS instance existence +2. **Namespace Preparation** - Creates/updates `mas-{instance-id}-pipelines` namespace +3. **OpenShift Pipelines** - Validates or installs OpenShift Pipelines Operator +4. **PVC Creation** - Provisions persistent volume for backup storage +5. **Tekton Pipeline Launch** - Submits PipelineRun with configured parameters +6. **Component Backup** - Executes backup tasks in parallel where possible: + - IBM Catalogs backup + - Certificate Manager backup + - MongoDB backup + - SLS backup (if included) +7. **Suite Backup** - Backs up MAS core configuration +8. **Database Backup** (optional) - Backs up Db2 instance and database: + - Db2 instance resources backup + - Db2 database backup (online or offline) +9. **Application Backup** (optional) - Backs up MAS application resources and persistent volumes: + - Manage namespace resources backup + - Manage persistent volume data backup +10. **Archive Creation** - Compresses backup into tar.gz archives for each component +11. **Upload** (optional) - Uploads archives to S3 or Artifactory +12. **Workspace Cleanup** (optional, default: enabled) - Cleans backup and config workspaces to free up storage + +### Monitoring Progress + +After launching the backup, a URL to the Tekton PipelineRun is displayed: + +``` +View progress: + https://console-openshift-console.apps.cluster.example.com/k8s/ns/mas-inst1-pipelines/tekton.dev~v1beta1~PipelineRun/mas-backup-20240315-120000 +``` + +Use this URL to: + +- Monitor real-time backup progress +- View logs from individual backup tasks +- Troubleshoot any failures +- Verify successful completion + +### Workspace Cleanup + +By default, the backup pipeline automatically cleans the workspace directories after backup completion to free up storage space. This cleanup occurs in the pipeline's `finally` block, ensuring it runs regardless of backup success or failure. + +**To disable workspace cleanup:** + +- **Interactive mode**: Answer "No" when prompted about cleaning workspaces +- **Non-interactive mode**: Use the `--no-clean-backup` flag + +**When to disable cleanup:** + +- Troubleshooting backup issues and need to inspect workspace contents +- Running multiple backups in sequence and want to preserve intermediate files +- Custom post-backup processing that requires access to workspace files + +!!! tip + Workspace cleanup is recommended for production backups to prevent PVC storage exhaustion. Only disable it when you have a specific need to inspect or process the workspace contents. + + +Best Practices +------------------------------------------------------------------------------- + +### Backup Strategy + +1. **Regular Schedule** - Implement automated backups on a regular schedule +2. **Version Naming** - Use descriptive backup versions (e.g., `prod-20240315-pre-upgrade`) +3. **Retention Policy** - Define how long to keep backups based on compliance requirements +4. **Off-site Storage** - Upload backups to S3 or Artifactory for disaster recovery +5. **Test Restores** - Periodically test restore procedures in non-production environments +6. **Document Configuration** - Keep records of custom configurations and dependencies +7. **Application Backups** - Include Manage application and Db2 database in regular backup schedule +8. **Coordinate Backups** - When backing up Manage, always include the Db2 database for consistency +9. **Storage Planning** - Allocate sufficient backup storage when including applications and databases (100Gi+ recommended) + +### Security Considerations + +1. **Credentials** - Never hardcode credentials in scripts; use environment variables or secrets +2. **Access Control** - Restrict access to backup storage and archives +3. **Encryption** - Consider encrypting backup archives for sensitive environments +4. **Audit Trail** - Maintain logs of backup operations and access + +### Automation + +For automated backups, you have several options depending on your infrastructure and requirements: + +#### Option 1: Shell Script with MAS CLI + +Create a simple shell script or CI/CD pipeline using the MAS CLI: + +```bash +#!/bin/bash +# Automated MAS Backup Script + +INSTANCE_ID="inst1" +BACKUP_VERSION="auto-$(date +%Y%m%d-%H%M%S)" +S3_BUCKET="mas-backups-prod" + +# Login to OpenShift +oc login --token=${OCP_TOKEN} --server=${OCP_SERVER} + +# Run backup with S3 upload +docker run --rm \ + -v ~/.kube:/root/.kube:z \ + -v ~:/mnt/home \ + quay.io/ibmmas/cli mas backup \ + --instance-id ${INSTANCE_ID} \ + --backup-version ${BACKUP_VERSION} \ + --backup-storage-size 50Gi \ + --upload-backup \ + --aws-access-key-id ${AWS_ACCESS_KEY_ID} \ + --aws-secret-access-key ${AWS_SECRET_ACCESS_KEY} \ + --s3-bucket-name ${S3_BUCKET} \ + --s3-region us-east-1 \ + --no-confirm + +# Check exit code +if [ $? -eq 0 ]; then + echo "Backup completed successfully: ${BACKUP_VERSION}" +else + echo "Backup failed!" + exit 1 +fi +``` + +#### Option 2: Red Hat Ansible Automation Platform + +For enterprise-grade automation with advanced features, use **Red Hat Ansible Automation Platform (AAP)** to execute the backup playbooks and roles directly. The [MAS DevOps Execution Environment](https://ibm-mas.github.io/ansible-devops/execution-environment/) provides a pre-built container image (`quay.io/ibmmas/ansible-devops-ee`) that includes the `ibm.mas_devops` collection and all required dependencies. + +**Benefits of using AAP:** + +- **Centralized Management** - Single control plane for all automation +- **Role-Based Access Control (RBAC)** - Fine-grained permissions for backup operations +- **Scheduling** - Built-in job scheduling for regular backups +- **Audit Logging** - Complete audit trail of all backup operations +- **Credential Management** - Secure storage and injection of credentials +- **Notifications** - Integration with email, Slack, PagerDuty, and other systems +- **Job Templates** - Reusable backup configurations +- **Workflow Automation** - Chain backup with other operations (e.g., validation, upload) + +**To use AAP for MAS backups:** + +1. **Configure the Execution Environment** - Set up AAP to use the `quay.io/ibmmas/ansible-devops-ee` image (see [Execution Environment setup guide](https://ibm-mas.github.io/ansible-devops/execution-environment/)) +2. **Create a Project** - Point to your playbook repository (or use the sample playbooks as a starting point) +3. **Create Job Templates** - Configure job templates for backup operations using the [`ibm.mas_devops.br_core`](https://ibm-mas.github.io/ansible-devops/playbooks/backup-restore/) playbook +4. **Configure Credentials** - Set up OpenShift credentials and any cloud storage credentials +5. **Schedule Backups** - Set up recurring schedules for automated backups +6. **Configure Notifications** - Set up alerts for backup success/failure + +**Example AAP Job Template Variables:** + +```yaml +mas_instance_id: inst1 +br_action: backup +mas_backup_dir: /backup/mas +backup_version: "{{ ansible_date_time.date }}-{{ ansible_date_time.hour }}{{ ansible_date_time.minute }}" +include_sls: true +mongodb_namespace: mongoce +``` + +For detailed information on setting up and using Ansible Automation Platform with MAS DevOps, see: +- [MAS DevOps Execution Environment](https://ibm-mas.github.io/ansible-devops/execution-environment/) - Complete AAP setup guide +- [Backup and Restore Playbook](https://ibm-mas.github.io/ansible-devops/playbooks/backup-restore/) - Playbook documentation and examples + +!!! tip + AAP is recommended for production environments where you need enterprise features like RBAC, audit logging, and centralized management. For simpler use cases, the MAS CLI with shell scripts may be sufficient. + + +Troubleshooting +------------------------------------------------------------------------------- + +### Common Issues + +**Issue: "No MAS instances were detected on the cluster"** + +- Verify you're connected to the correct OpenShift cluster +- Ensure MAS is installed and the Suite CR exists +- Check that you have permissions to view Suite resources + +**Issue: "OpenShift Pipelines Operator installation failed"** + +- Verify cluster admin permissions +- Check cluster connectivity and operator hub availability +- Review operator installation logs + +**Issue: "Insufficient storage for backup PVC"** + +- Increase `--backup-storage-size` parameter +- Verify storage class has available capacity +- Check cluster storage quotas + +**Issue: "MongoDB backup failed"** + +- Verify MongoDB namespace and instance name are correct +- Ensure MongoDB is running and accessible +- Check MongoDB provider is set to `community` + +**Issue: "SLS backup failed"** + +- Verify SLS namespace is correct +- Ensure SLS is running and accessible +- Consider using `--exclude-sls` if SLS is external + +**Issue: "Upload to S3 failed"** + +- Verify AWS credentials are correct +- Check S3 bucket exists and is accessible +- Verify network connectivity to AWS +- Ensure IAM permissions allow PutObject operations + +**Issue: "Manage application backup failed"** + +- Verify Manage workspace ID is correct +- Ensure ManageWorkspace CR exists in the cluster +- Check that Manage pods are running and healthy +- Verify persistent volumes are properly configured in ManageWorkspace CR +- Ensure sufficient storage space in backup PVC + +**Issue: "Db2 backup failed"** + +- Verify Db2 namespace and instance name are correct +- Ensure Db2 instance is running and accessible +- Check backup type matches Db2 logging configuration (use offline for circular logging) +- Verify sufficient storage space in Db2 backup PVC +- Review Db2 pod logs for database-specific errors + +**Issue: "Manage persistent volume backup is slow"** + +- PV backup duration depends on data volume +- Large JMS server or attachment PVCs can take significant time +- Monitor backup progress in Tekton pipeline logs +- Consider scheduling backups during maintenance windows +- Ensure network bandwidth is sufficient for data transfer diff --git a/docs/guides/configure-airgap.md b/docs/guides/configure-airgap.md new file mode 100644 index 00000000000..451907ca668 --- /dev/null +++ b/docs/guides/configure-airgap.md @@ -0,0 +1,400 @@ +Configure OpenShift for Airgap Install +=============================================================================== + +Overview +------------------------------------------------------------------------------- +The MAS CLI provides automated configuration of airgap (disconnected) OpenShift environments for Maximo Application Suite installations. Airgap configuration enables OpenShift clusters without direct internet access to pull container images from a private registry by configuring ImageDigestMirrorSet (IDMS) resources. + +This guide covers the complete process of configuring an OpenShift cluster to use a private container registry for airgap deployments. + +!!! warning "ROKS Limitation" + The `configure-airgap` command does not work on **IBM Cloud ROKS** clusters. This is a limitation of the IBM Cloud ROKS service which disables key parts of OpenShift functionality required to configure and use ImageDigestMirrorSet resources (which is the basis of airgap/image mirroring support in OpenShift). + + +Understanding Airgap Configuration +------------------------------------------------------------------------------- + +### What is Airgap? +An airgap (or air-gapped) environment is a network security measure where a computer or network is physically isolated from unsecured networks, including the internet. In the context of OpenShift and MAS: + +- Cluster has no direct internet connectivity +- Cannot pull images from public registries (quay.io, docker.io, etc.) +- Requires all container images to be available in a private registry +- Uses ImageDigestMirrorSet (IDMS) to redirect image pulls to private registry + +### How Airgap Works + +1. Application requests image from `quay.io/ibmmas/example:latest` +2. IDMS instructs Kubernetes to redirect request to `private-registry.company.com/ibmmas/example:latest` +3. Image is pulled from private registry instead of public registry + +### Prerequisites for Airgap +Before configuring airgap, you must: + +1. **Mirror Images** - Copy all required images to your private registry +2. **Private Registry** - Have a functioning private container registry +3. **Network Access** - Cluster must have network access to private registry +4. **Registry Credentials** - Authentication credentials for the private registry + + +Preparation +------------------------------------------------------------------------------- + +### Private Container Registry +You must have a private container registry accessible from your OpenShift cluster. Supported registries include: + +- **Red Hat Quay** - Enterprise container registry +- **Harbor** - Open source container registry +- **Artifactory** - Universal artifact repository +- **Docker Registry** - Simple registry implementation +- **AWS ECR** - Amazon Elastic Container Registry +- **Azure ACR** - Azure Container Registry + +The registry must: +- Be accessible from the OpenShift cluster network +- Support Docker Registry HTTP API V2 +- Have sufficient storage for mirrored images +- Support authentication (username/password or token) + +### Registry Certificate +If your private registry uses TLS with a custom certificate authority (CA): + +1. Obtain the CA certificate file (`.crt` or `.pem` format) +2. Save it to a location accessible to the CLI +3. Note the file path for use during configuration + +!!! tip + Self-signed certificates are common in private registries. The CLI can configure OpenShift to trust your custom CA. + +### Registry Credentials +Prepare authentication credentials for your private registry: + +- **Username** - Registry username or service account +- **Password** - Registry password or access token +- **Registry URL** - Full registry hostname and port + +Example registry URLs: +- `registry.company.com:5000` +- `harbor.internal.net` +- `quay.enterprise.com` + +### Mirrored Images +Before configuring airgap, ensure all required images are mirrored to your private registry: + +- **MAS Operator Images** - Core MAS operators and dependencies +- **Application Images** - MAS application images (Manage, Monitor, etc.) +- **Dependency Images** - MongoDB, Db2, Certificate Manager, etc. +- **Red Hat Images** - OpenShift operators and components + +Refer to the [Image Mirroring Guide](image-mirroring.md) for detailed mirroring instructions. + + +Configuration Process +------------------------------------------------------------------------------- + +### How Airgap Configuration Works +The `configure-airgap` command performs the following steps: + +1. **Validates Registry Access** - Tests connectivity to private registry +2. **Creates Pull Secret** - Configures registry authentication +3. **Creates IDMS Resources** - Configures image source redirection +4. **Trusts CA Certificate** - Adds custom CA to cluster trust (if provided) +5. **Restarts Machine Config** - Applies configuration to all nodes + +!!! note + Node restarts are required to apply IDMS configuration. The cluster will experience a rolling restart of all nodes, which may take 30-60 minutes depending on cluster size. + +### Interactive Mode +Interactive mode guides you through the configuration process with prompts for all required information. + +```bash +docker run -ti --rm -v ~:/mnt/local --pull always quay.io/ibmmas/cli mas configure-airgap +``` + +The interactive session will: + +1. Prompt for OpenShift cluster connection +2. Request private registry details (hostname, port) +3. Request registry credentials (username, password) +4. Optionally request CA certificate file path +5. Display configuration summary +6. Request confirmation before applying changes + +### Non-Interactive Mode +Non-interactive mode is ideal for automation and scripting. All required parameters must be provided via command-line arguments. + +```bash +docker run -ti --rm -v ~:/mnt/local --pull always quay.io/ibmmas/cli mas configure-airgap \ + -H registry.company.com \ + -P 5000 \ + -u $REGISTRY_USERNAME \ + -p $REGISTRY_PASSWORD \ + --ca-file /mnt/local/registry-ca.crt \ + --no-confirm +``` + + +Configuration Examples +------------------------------------------------------------------------------- + +### Basic Configuration (No Custom CA) +Configure airgap with a registry using publicly trusted certificates: + +```bash +export REGISTRY_USERNAME=admin +export REGISTRY_PASSWORD=secure-password + +docker run -ti --rm --pull always quay.io/ibmmas/cli mas configure-airgap \ + -H registry.company.com \ + -P 443 \ + -u $REGISTRY_USERNAME \ + -p $REGISTRY_PASSWORD \ + --no-confirm +``` + +### Configuration with Custom CA Certificate +Configure airgap with a registry using self-signed or custom CA certificates: + +```bash +# Save CA certificate to local directory +cat > ~/registry-ca.crt < +``` + + +#### Check Pull Secret +```bash +# Verify pull secret includes private registry +oc get secret pull-secret -n openshift-config -o jsonpath='{.data.\.dockerconfigjson}' | base64 -d | jq +``` + +#### Check CA Trust +If you provided a CA certificate: + +```bash +# Verify CA is in cluster trust bundle +oc get configmap -n openshift-config user-ca-bundle -o yaml +``` + +#### Test Image Pull +Test pulling an image from your private registry: + +```bash +# Create test pod +oc run test-pull --image=registry.company.com:5000/ibmmas/cli:latest --restart=Never + +# Check pod status +oc get pod test-pull + +# Clean up +oc delete pod test-pull +``` + +### Next Steps +With airgap configuration complete, you can proceed to: + +- [Install MAS](install.md) in the airgap environment +- Configure additional registry mirrors if needed +- Set up monitoring for registry connectivity + + +Troubleshooting +------------------------------------------------------------------------------- + +### Configuration Failures + +**Registry Not Accessible** +``` +Error: Unable to connect to registry +``` +- Verify registry hostname and port are correct +- Check network connectivity from cluster to registry +- Ensure firewall rules allow traffic +- Test connectivity: `curl -k https://registry.company.com:5000/v2/` + +**Authentication Failed** +``` +Error: Authentication to registry failed +``` +- Verify username and password are correct +- Check if credentials have expired +- Ensure user has pull permissions +- Test authentication: `docker login registry.company.com:5000` + +**Invalid CA Certificate** +``` +Error: CA certificate validation failed +``` +- Verify CA certificate file is in correct format (PEM) +- Ensure certificate is not expired +- Check certificate includes full chain if needed +- Validate certificate: `openssl x509 -in ca.crt -text -noout` + +### Node Restart Issues + +**Nodes Stuck in Updating State** +``` +NAME UPDATED UPDATING DEGRADED +worker False True False +``` +- Check machine config operator logs: `oc logs -n openshift-machine-config-operator ` +- Review node status: `oc describe node ` +- Check for resource constraints or disk space issues +- Wait longer - large clusters may take 60+ minutes + +**Nodes in Degraded State** +``` +NAME UPDATED UPDATING DEGRADED +worker False False True +``` +- Check machine config daemon logs: `oc logs -n openshift-machine-config-operator ` +- Review node events: `oc get events -n openshift-machine-config-operator` +- Check for configuration conflicts +- May require manual intervention or rollback + +### Image Pull Failures + +**Images Not Found in Private Registry** +``` +Error: Failed to pull image: manifest unknown +``` +- Verify images are mirrored to private registry +- Check image paths match IDMS configuration +- Ensure registry namespace structure is correct +- Review mirroring logs for errors + +**IDMS Not Applied** +``` +Error: Still pulling from public registry +``` +- Verify IDMS resources exist: `oc get imagedigestmirrorset` +- Check machine config pools are updated: `oc get mcp` +- Ensure nodes have restarted +- Review IDMS configuration for errors + +**Certificate Trust Issues** +``` +Error: x509: certificate signed by unknown authority +``` +- Verify CA certificate was provided during configuration +- Check CA is in cluster trust bundle +- Ensure certificate is valid and not expired +- May need to reconfigure with correct CA + +### Registry Connectivity + +**Intermittent Connection Failures** +``` +Error: Timeout connecting to registry +``` +- Check network stability between cluster and registry +- Verify registry is not overloaded +- Review registry logs for errors +- Consider increasing timeout values + +**DNS Resolution Failures** +``` +Error: Cannot resolve registry hostname +``` +- Verify DNS configuration in cluster +- Check if registry hostname is resolvable: `oc debug node/ -- chroot /host nslookup registry.company.com` +- Consider using IP address instead of hostname +- Verify DNS servers are accessible diff --git a/docs/guides/install.md b/docs/guides/install.md index 1e7e12e082e..1b3fe8b0090 100644 --- a/docs/guides/install.md +++ b/docs/guides/install.md @@ -1,14 +1,6 @@ Installation =============================================================================== -:::mas-cli-usage -module: mas.cli.install.argParser -parser: installArgParser -ignore_description: true -ignore_epilog: true -::: - - Preparation ------------------------------------------------------------------------------- ### IBM Entitlement Key @@ -34,9 +26,9 @@ The other values can be left at their defaults. Finally, click **Generate** and ### OpenShift Container Platform You should already have a target OpenShift cluster ready to install Maximo Application suite into. If you do not already have one then refer to the [OpenShift Container Platform installation overview](https://docs.redhat.com/en/documentation/openshift_container_platform/4.20/html/installation_overview/index). The CLI also supports OpenShift provisioning in many hyperscaler providers: -- [AWS](../commands/provision-rosa.md) -- [IBM Cloud](../commands/provision-roks.md) -- [IBM DevIT FYRE (Internal)](../commands/provision-fyre.md) +- [AWS](provision-aws.md) +- [IBM Cloud](provision-roks.md) +- [IBM DevIT FYRE (Internal)](provision-fyre.md) IBM Maximo Application Suite is designed to run on a continuously evolving OpenShift platform. Red Hat regularly updates its operator catalogs (including the Community Operators catalog that provides components such as Grafana), and these updates can sometimes introduce breaking changes. To ensure stable, reproducible installations, it is essential to align the versions of OpenShift, Red Hat operator catalogs, the IBM Maximo operator catalog, and the MAS CLI. @@ -186,7 +178,7 @@ You must have a production grade Docker v2 compatible registry such as [Quay Ent docker run -ti --rm --pull always quay.io/ibmmas/cli mas setup-registry ``` -The registry will be setup running on port 32500. For more details on this step, refer to the [setup-registry](../commands/setup-registry.md) command's documentation. Regardless of whether you set up a new registry or already had one, you need to collect the following information about your private registry: +The registry will be setup running on port 32500. For more details on this step, refer to the [setup-registry](private-registry.md#registry-deployment) command's documentation. Regardless of whether you set up a new registry or already had one, you need to collect the following information about your private registry: | Name | Detail | | ------------------- | ------------------------------------------------------------------------------------------------------------------ | @@ -210,7 +202,7 @@ For full details on this process review the [image mirroring](image-mirroring.md ### Configure OpenShift to use your Private Registry -Your cluster must be configured to use the private registry as a mirror for the MAS container images. An `ImageContentSourcePolicy` named `mas-and-dependencies` will be created in the cluster, this is also the resource that the MAS install will use to detect whether the installation is a disconnected install and tailor the options presented when you run the `mas install` command. +Your cluster must be configured to use the private registry as a mirror for the MAS container images. An `ImageDigestMirrorSet` named `mas-and-dependencies` will be created in the cluster, this is also the resource that the MAS install will use to detect whether the installation is a disconnected install and tailor the options presented when you run the `mas install` command. ```bash docker run -ti --pull always quay.io/ibmmas/cli mas configure-airgap @@ -221,7 +213,7 @@ docker run -ti --pull always quay.io/ibmmas/cli mas configure-airgap --setup-red ``` You will be prompted to provide information about the private registry, including the CA certificate necessary to configure your cluster to trust the private registry. -This command can also be ran non-interactive, for full details refer to the [configure-airgap](../commands/configure-airgap.md) command documentation. +This command can also be ran non-interactive, for full details refer to the [configure-airgap](configure-airgap.md) command documentation. ```bash mas configure-airgap \ @@ -388,6 +380,14 @@ docker run -e IBM_ENTITLEMENT_KEY -e SUPERUSER_PASSWORD -ti --rm -v ~:/mnt/home ``` +:::mas-cli-usage +module: mas.cli.install.argParser +parser: installArgParser +ignore_description: true +ignore_epilog: true +::: + + How It Works ------------------------------------------------------------------------------- The engine that performs all tasks is written in Ansible, you can directly use the same automation outside of this CLI if you wish. The code is open source and available in [ibm-mas/ansible-devops](https://github.com/ibm-mas/ansible-devops), the collection is also available to install directly from [Ansible Galaxy](https://galaxy.ansible.com/ibm/mas_devops), the install supports the following actions: diff --git a/docs/guides/private-registry.md b/docs/guides/private-registry.md new file mode 100644 index 00000000000..37a5ac923e4 --- /dev/null +++ b/docs/guides/private-registry.md @@ -0,0 +1,246 @@ +Private Container Registry Management +=============================================================================== + +Overview +------------------------------------------------------------------------------- +The MAS CLI provides automated deployment and management of a private container registry within your OpenShift cluster. This in-cluster registry is essential for airgap (disconnected) environments where direct access to public container registries is not available. + +!!! tip + This in-cluster private registry is ideal for development and test environments. For production deployments, consider enterprise registry solutions like Red Hat Quay or Harbor. + + +Understanding Private Registries +------------------------------------------------------------------------------- + +### What is a Private Registry? +A private container registry is a secure repository for storing and distributing container images within your organization. In the context of OpenShift and MAS: + +- Stores mirrored container images from public registries +- Provides local image distribution without internet access +- Enables airgap deployments +- Reduces external bandwidth usage +- Improves image pull performance + +### When to Use In-Cluster Registry +The MAS CLI's in-cluster registry is suitable for: + +- **Airgap Environments** - Clusters without internet access +- **Development and Testing** - Quick setup for non-production environments +- **Proof of Concept** - Demonstrating MAS in disconnected scenarios +- **Temporary Deployments** - Short-term testing or migration scenarios + +### When to Use External Registry +Consider external registry solutions for: + +- **Production Deployments** - Enterprise-grade reliability and support +- **Multi-Cluster Environments** - Shared registry across multiple clusters +- **High Availability Requirements** - Redundancy and disaster recovery +- **Advanced Features** - Image scanning, replication, access control + + +Preparation +------------------------------------------------------------------------------- + +### Cluster Requirements +Before deploying a private registry, ensure your cluster meets these requirements: + +**Storage:** +- Available storage class for persistent volumes +- Sufficient storage capacity (minimum 500 GB, recommended 2000 GB+) +- Storage class supporting ReadWriteOnce (RWO) access mode + +**Network:** +- LoadBalancer service type support (for external access) +- Or NodePort service type (alternative for clusters without LoadBalancer) +- Network connectivity between cluster nodes and registry + +**Resources:** +- Sufficient CPU and memory for registry pods +- Available namespace for registry deployment + +### Storage Class Selection +Choose an appropriate storage class based on your environment: + +| Environment | Recommended Storage Class | Notes | +|-------------|--------------------------|-------| +| **IBM Cloud ROKS** | `ibmc-block-gold` | High-performance block storage | +| **AWS** | `gp3-csi` or `gp2-csi` | General purpose SSD | +| **Azure** | `managed-premium` | Premium SSD | +| **On-Premises** | `nfs-client` or `local-storage` | Depends on infrastructure | +| **OpenShift Data Foundation** | `ocs-storagecluster-ceph-rbd` | Ceph block storage | + +To list available storage classes: +```bash +oc get storageclass +``` + +### Registry Credentials +Prepare credentials for registry authentication: + +- **Username** - Registry admin username +- **Password** - Strong password for registry access + +!!! warning "Security" + Use a strong, unique password for the registry. This password will be used to authenticate all image push and pull operations. + + +Registry Deployment +------------------------------------------------------------------------------- + +### How Registry Setup Works +The `setup-registry` command performs the following steps: + +1. **Creates Namespace** - Deploys registry in dedicated namespace +2. **Configures Storage** - Creates PersistentVolumeClaim for image storage +3. **Deploys Registry** - Installs Docker Registry v2 container +4. **Generates Certificates** - Creates self-signed TLS certificates +5. **Creates Service** - Exposes registry via LoadBalancer or NodePort +6. **Configures Authentication** - Sets up basic authentication with provided credentials + +### Interactive Mode +Interactive mode guides you through the deployment process with prompts for all configuration options. + +```bash +docker run -ti --rm --pull always quay.io/ibmmas/cli mas setup-registry +``` + +The interactive session will: + +1. Prompt for OpenShift cluster connection +2. Request registry credentials (username, password) +3. Request namespace name (default: `airgap-registry`) +4. Request storage class +5. Request storage capacity (default: `2000Gi`) +6. Request service type (LoadBalancer or NodePort) +7. Display configuration summary +8. Request confirmation before deployment + +### Non-Interactive Mode +Non-interactive mode is ideal for automation and scripting. All required parameters must be provided via command-line arguments. + +```bash +export REGISTRY_PASSWORD=secure-password + +docker run -ti --rm --pull always quay.io/ibmmas/cli mas setup-registry \ + -u registry-admin \ + -p $REGISTRY_PASSWORD \ + -n airgap-registry \ + -s ibmc-block-gold \ + -c 2000Gi \ + -t loadbalancer \ + --no-confirm +``` + +Command Reference +------------------------------------------------------------------------------- + +### Setup Registry + +#### Required Parameters +- `-u, --username REGISTRY_USERNAME` - Registry admin username (required) +- `-p, --password REGISTRY_PASSWORD` - Registry admin password (required) + +#### Optional Parameters +- `-n, --namespace REGISTRY_NAMESPACE` - Registry namespace (default: `airgap-registry`) +- `-s, --storage-class STORAGE_CLASS` - Storage class for PVC (default: `ibmc-block-gold`) +- `-c, --storage-capacity STORAGE_CAPACITY` - Storage capacity (default: `2000Gi`) +- `-t, --service-type SERVICE_TYPE` - Service type: `loadbalancer` or `nodeport` (default: `loadbalancer`) + +#### Other Options +- `--no-confirm` - Skip confirmation prompt +- `-h, --help` - Display help message + + +Post-Deployment Steps +------------------------------------------------------------------------------- + +### Accessing the Registry +After deployment completes, retrieve registry access information: + +```bash +# Get registry service details +oc get svc -n airgap-registry + +# Get registry hostname/IP +oc get svc -n airgap-registry -o jsonpath='{.items[0].status.loadBalancer.ingress[0].hostname}' + +# For NodePort service +oc get svc -n airgap-registry -o jsonpath='{.items[0].spec.ports[0].nodePort}' +``` + +### Retrieving CA Certificate +The registry uses self-signed certificates. Retrieve the CA certificate for client configuration: + +```bash +# Extract CA certificate +oc get secret -n airgap-registry registry-tls -o jsonpath='{.data.ca\.crt}' | base64 -d > registry-ca.crt +``` + +### Testing Registry Access +Test registry connectivity and authentication: + +```bash +# Test with curl (replace with your registry hostname) +curl -k -u admin:password https://registry.example.com:5000/v2/ + +# Expected response: {} +``` + +### Configuring Docker/Podman +Configure your local Docker or Podman to trust the registry: + +```bash +# Copy CA certificate to Docker trust store +sudo mkdir -p /etc/docker/certs.d/registry.example.com:5000 +sudo cp registry-ca.crt /etc/docker/certs.d/registry.example.com:5000/ca.crt + +# Test login +docker login registry.example.com:5000 -u admin -p password +``` + +### Next Steps +With your private registry deployed, you can proceed to: + +- [Mirror images](image-mirroring.md) to the registry +- [Configure airgap](configure-airgap.md) environment +- [Install MAS](install.md) using the private registry + + +Registry Removal +------------------------------------------------------------------------------- + +### Understanding Registry Teardown +The `teardown-registry` command permanently removes the registry and all its data. This operation: + +- Deletes the registry namespace and all resources +- Removes the PersistentVolumeClaim and stored images +- Deletes TLS certificates and authentication secrets +- Cannot be undone - all registry data is lost + +!!! danger "Data Loss Warning" + The `teardown-registry` command permanently deletes all registry data, including all stored container images. Ensure you have backups or can re-mirror images before proceeding. + +### Interactive Teardown +Interactive mode prompts for confirmation before deletion: + +```bash +docker run -ti --rm --pull always quay.io/ibmmas/cli mas teardown-registry +``` + +### Non-Interactive Teardown +Non-interactive mode for automation (use with caution): + +```bash +docker run -ti --rm --pull always quay.io/ibmmas/cli mas teardown-registry \ + -n airgap-registry \ + --no-confirm +``` + +### Teardown Command Reference + +#### Optional Parameters +- `-n, --namespace REGISTRY_NAMESPACE` - Registry namespace to remove (default: `airgap-registry`) + +#### Other Options +- `--no-confirm` - Skip confirmation prompt (dangerous) +- `-h, --help` - Display help message diff --git a/docs/guides/provision-aws.md b/docs/guides/provision-aws.md new file mode 100644 index 00000000000..85c02e927fa --- /dev/null +++ b/docs/guides/provision-aws.md @@ -0,0 +1,31 @@ +Provision OpenShift on AWS +=============================================================================== + +Overview +------------------------------------------------------------------------------- +The MAS CLI provides automated provisioning of OpenShift clusters on AWS using Installer Provisioned Infrastructure (IPI). + + +Provisioning Modes +------------------------------------------------------------------------------- + +### Interactive Mode +Interactive mode guides you through the provisioning process with prompts for all configuration options. + +```bash +docker run -ti --rm --pull always quay.io/ibmmas/cli mas provision-aws +``` + +The interactive session will: + +1. Verify AWS credentials +2. Request cluster configuration details +3. Configure instance specifications +4. Set up networking options +5. Display a summary and request confirmation + +### Non-Interactive Mode +Non-interactive mode is ideal for automation and scripting. All required parameters must be provided via command-line arguments or environment variables. + +!!! note + Detailed non-interactive parameters are available via `mas provision-aws --help` diff --git a/docs/guides/provision-fyre.md b/docs/guides/provision-fyre.md new file mode 100644 index 00000000000..a2855bf6018 --- /dev/null +++ b/docs/guides/provision-fyre.md @@ -0,0 +1,357 @@ +Provision OpenShift on IBM DevIT FYRE +=============================================================================== + +!!! warning "Internal IBM Use Only" + FYRE (Functional Verification Environment) is an internal IBM development and testing platform. This guide is intended for IBM employees and authorized users only. + +Overview +------------------------------------------------------------------------------- +The MAS CLI provides automated provisioning of OpenShift Container Platform clusters on IBM's internal FYRE infrastructure. FYRE offers rapid cluster deployment for development, testing, and demonstration purposes with flexible resource allocation and quota management. + +This guide covers the complete process of provisioning an OpenShift cluster on FYRE, from obtaining credentials to configuring storage providers. + +!!! tip + FYRE clusters are ideal for short-term development and testing. For production deployments, use supported cloud providers like AWS, Azure, or IBM Cloud. + + +Preparation +------------------------------------------------------------------------------- + +### FYRE Account and Credentials +You must have an active FYRE account with appropriate quota allocation. To obtain FYRE credentials: + +1. Access the [FYRE Portal](https://fyre.ibm.com) +2. Log in with your IBM credentials +3. Navigate to **Account Settings** to retrieve your API key +4. Note your username and API key for use with the CLI + +### Product Group and Quota +FYRE uses product groups to organize and allocate resources. You will need: + +- **Product Group ID** - The numeric identifier for your product group +- **Quota Type** - Either `quick_burn` (temporary, time-limited) or `product_group` (allocated quota) + +Contact your FYRE administrator if you need assistance with product group access or quota allocation. + +### OpenShift Version Selection +Choose an OpenShift version supported by both FYRE and your target MAS version. Refer to the [MAS system requirements](https://www.ibm.com/docs/en/mas-cd/continuous-delivery) for version compatibility. + + +Cluster Configuration +------------------------------------------------------------------------------- + +### Cluster Naming +Cluster names must: + +- Use lowercase letters only +- Be unique within your FYRE account +- Be descriptive for easy identification +- Follow your organization's naming conventions + +Example: `mas-dev-cluster`, `test-env-01` + +### Worker Node Sizing +Configure worker nodes based on your workload requirements: + +| Configuration | CPU | Memory | Use Case | +|---------------|-----|--------|----------| +| **Small** | 4 | 16 GB | Development, testing | +| **Medium** | 8 | 32 GB | Standard MAS installation | +| **Large** | 16 | 64 GB | Production-like environments | + +!!! note + MAS requires a minimum of 3 worker nodes for high availability. Each worker should have at least 8 CPUs and 32 GB memory for production-like installations. + +### Additional Storage Disks +FYRE allows attaching additional disks to worker nodes for storage providers like ODF or Longhorn. Specify disk sizes as a comma-separated list: + +- `200,200` - Two 200 GB disks per worker +- `500` - One 500 GB disk per worker + +Additional disks are required when using ODF (OpenShift Data Foundation) for persistent storage. + +### Storage Provider Options +The CLI can automatically configure storage providers: + +- **NFS** - Network File System, simple and fast setup +- **ODF** - OpenShift Data Foundation, production-grade storage +- **Longhorn** - Cloud-native distributed storage + +!!! tip + For development and testing, NFS provides the fastest setup. For production-like environments, use ODF. + + +Provisioning Modes +------------------------------------------------------------------------------- + +### Interactive Mode +Interactive mode guides you through the provisioning process with prompts for all configuration options. + +```bash +docker run -ti --rm --pull always quay.io/ibmmas/cli mas provision-fyre +``` + +The interactive session will: + +1. Prompt for FYRE credentials +2. Request cluster configuration details +3. Configure worker node specifications +4. Optionally configure storage provider +5. Display a summary and request confirmation + +### Non-Interactive Mode +Non-interactive mode is ideal for automation and scripting. All required parameters must be provided via command-line arguments or environment variables. + +```bash +export FYRE_USERNAME=your-username +export FYRE_APIKEY=your-api-key + +docker run -ti --rm --pull always quay.io/ibmmas/cli mas provision-fyre \ + -u $FYRE_USERNAME \ + -a $FYRE_APIKEY \ + -p 225 \ + -q product_group \ + -c mas-dev-cluster \ + -d "MAS Development Cluster" \ + -v 4.15 \ + --worker-count 3 \ + --worker-cpu 8 \ + --worker-memory 32 \ + --no-confirm +``` + + +Configuration Examples +------------------------------------------------------------------------------- + +### Basic Development Cluster +Minimal configuration for development and testing: + +```bash +docker run -ti --rm --pull always quay.io/ibmmas/cli mas provision-fyre \ + -u $FYRE_USERNAME \ + -a $FYRE_APIKEY \ + -p 225 \ + -q quick_burn \ + -c dev-cluster \ + -v 4.15 \ + --worker-count 3 \ + --worker-cpu 4 \ + --worker-memory 16 \ + --storage nfs \ + --no-confirm +``` + +### Standard MAS Installation Cluster +Recommended configuration for typical MAS installations: + +```bash +docker run -ti --rm --pull always quay.io/ibmmas/cli mas provision-fyre \ + -u $FYRE_USERNAME \ + -a $FYRE_APIKEY \ + -p 225 \ + -q product_group \ + -c mas-standard \ + -d "MAS Standard Installation" \ + -v 4.15 \ + --worker-count 3 \ + --worker-cpu 8 \ + --worker-memory 32 \ + --storage nfs \ + --nfs-image-registry-size 100 \ + --no-confirm +``` + +### Cluster with ODF Storage +Configuration with OpenShift Data Foundation for production-like storage: + +```bash +docker run -ti --rm --pull always quay.io/ibmmas/cli mas provision-fyre \ + -u $FYRE_USERNAME \ + -a $FYRE_APIKEY \ + -p 225 \ + -q product_group \ + -c mas-odf-cluster \ + -d "MAS Cluster with ODF" \ + -v 4.15 \ + --worker-count 3 \ + --worker-cpu 16 \ + --worker-memory 64 \ + --worker-additional-disks "200,200" \ + --storage odf \ + --no-confirm +``` + +### Large Cluster for Performance Testing +High-resource configuration for performance testing: + +```bash +docker run -ti --rm --pull always quay.io/ibmmas/cli mas provision-fyre \ + -u $FYRE_USERNAME \ + -a $FYRE_APIKEY \ + -p 225 \ + -q product_group \ + -c mas-perf-test \ + -d "MAS Performance Testing" \ + -v 4.15 \ + --worker-count 5 \ + --worker-cpu 16 \ + --worker-memory 64 \ + --worker-additional-disks "500,500" \ + --storage odf \ + --no-confirm +``` + + +Command Reference +------------------------------------------------------------------------------- + +### FYRE Credentials +- `-u, --username FYRE_USERNAME` - FYRE username (required) +- `-a, --apikey FYRE_APIKEY` - FYRE API key (required) + +### Cluster Configuration +- `-p, --product-id FYRE_PRODUCT_ID` - FYRE product group ID (required) +- `-q, --quota-type FYRE_QUOTA_TYPE` - Quota type: `quick_burn` or `product_group` (required) +- `-c, --cluster-name CLUSTER_NAME` - Cluster name, lowercase only (required) +- `-v, --ocp-version OCP_VERSION` - OpenShift version, e.g., `4.14`, `4.15` (required) +- `-d, --description FYRE_DESCRIPTION` - Cluster description (optional) + +### Worker Node Configuration +- `--worker-count FYRE_WORKER_COUNT` - Number of worker nodes (default: 3) +- `--worker-cpu FYRE_WORKER_CPU` - CPUs per worker node (default: 8) +- `--worker-memory FYRE_WORKER_MEMORY` - Memory per worker in GB (default: 32) +- `--worker-additional-disks FYRE_WORKER_ADDITIONAL_DISKS` - Comma-separated disk sizes in GB (optional) +- `--fyre-cluster-size FYRE_CLUSTER_SIZE` - Quick burn size: `medium` or `large` (optional) + +### Storage Configuration +- `--storage` - Storage provider: `nfs`, `odf`, or `longhorn` (optional) +- `--nfs-image-registry-size FYRE_NFS_IMAGE_REGISTRY_SIZE` - NFS registry size in GB (default: 100) + +### Other Options +- `--no-confirm` - Skip confirmation prompt +- `-h, --help` - Display help message + + +Post-Provisioning Steps +------------------------------------------------------------------------------- + +### Accessing Your Cluster +After provisioning completes, the CLI will display: + +1. **Cluster URL** - OpenShift console access URL +2. **Kubeadmin Credentials** - Initial admin username and password +3. **API Server URL** - For CLI access + +Save these credentials securely. + +### Connecting with oc CLI +```bash +oc login --server=https://api.your-cluster.fyre.ibm.com:6443 \ + --username=kubeadmin \ + --password= +``` + +### Verifying Cluster Health +Check that all nodes are ready: + +```bash +oc get nodes +``` + +Verify storage classes are available: + +```bash +oc get storageclass +``` + +### Next Steps +With your FYRE cluster provisioned, you can proceed to: + +- [Install MAS](install.md) +- Configure additional cluster resources +- Set up monitoring and logging + + +Troubleshooting +------------------------------------------------------------------------------- + +### Provisioning Failures + +**Quota Exceeded** +``` +Error: Insufficient quota available +``` +- Verify your product group has available quota +- Contact your FYRE administrator to increase quota +- Use `quick_burn` quota for temporary clusters + +**Invalid Cluster Name** +``` +Error: Cluster name must be lowercase +``` +- Ensure cluster name contains only lowercase letters, numbers, and hyphens +- Avoid uppercase letters and special characters + +**Version Not Available** +``` +Error: OpenShift version not supported +``` +- Check available versions in the FYRE portal +- Use a supported version (typically 4.14, 4.15, or 4.16) + +### Storage Configuration Issues + +**NFS Registry Size Too Large** +``` +Error: Requested size exceeds available storage +``` +- Reduce `--nfs-image-registry-size` value +- Default 100 GB is usually sufficient + +**ODF Requires Additional Disks** +``` +Error: ODF requires additional disks on worker nodes +``` +- Add `--worker-additional-disks` parameter +- Minimum two disks recommended: `--worker-additional-disks "200,200"` + +### Connection Issues + +**Unable to Access Cluster** +- Verify you are on IBM network or VPN +- Check cluster status in FYRE portal +- Ensure firewall rules allow access + +**Authentication Failures** +- Verify credentials are correct +- Check if password has expired +- Try regenerating kubeadmin password in FYRE portal + + +Best Practices +------------------------------------------------------------------------------- + +### Resource Planning +- **Development**: 3 workers, 4 CPU, 16 GB memory +- **Testing**: 3 workers, 8 CPU, 32 GB memory +- **Production-like**: 5+ workers, 16 CPU, 64 GB memory + +### Quota Management +- Use `quick_burn` for short-term testing (auto-expires) +- Use `product_group` quota for longer-term environments +- Monitor quota usage regularly +- Clean up unused clusters promptly + +### Naming Conventions +- Include purpose in name: `mas-dev`, `mas-test`, `mas-demo` +- Add date for temporary clusters: `mas-test-20260520` +- Use team or project identifiers: `team-a-mas-dev` + +### Storage Selection +- **NFS**: Fast setup, good for development +- **ODF**: Production-grade, requires more resources +- **Longhorn**: Alternative to ODF, lighter weight + +!!! tip + Always provision with `--no-confirm` in automation scripts to avoid interactive prompts. \ No newline at end of file diff --git a/docs/guides/provision-roks.md b/docs/guides/provision-roks.md new file mode 100644 index 00000000000..c5df694c05d --- /dev/null +++ b/docs/guides/provision-roks.md @@ -0,0 +1,194 @@ +Provision OpenShift on IBM Cloud ROKS +=============================================================================== + +Overview +------------------------------------------------------------------------------- +The MAS CLI provides automated provisioning of Red Hat OpenShift Kubernetes Service (ROKS) clusters on IBM Cloud. ROKS is IBM's managed OpenShift offering that provides enterprise-grade Kubernetes with integrated IBM Cloud services, automated updates, and built-in security features. + +This guide covers the complete process of provisioning an OpenShift cluster on IBM Cloud ROKS, from obtaining credentials to configuring worker nodes and optional GPU support. + +!!! tip + ROKS clusters are ideal for production deployments with IBM Cloud integration, managed services, and enterprise support. + + +Preparation +------------------------------------------------------------------------------- + +### IBM Cloud Account +You must have an active IBM Cloud account with appropriate permissions. To get started: + +1. Create an account at [IBM Cloud](https://cloud.ibm.com) +2. Ensure you have access to create Kubernetes/OpenShift clusters +3. Verify billing is configured for your account + +### IBM Cloud API Key +Generate an API key for authentication: + +1. Log in to [IBM Cloud](https://cloud.ibm.com) +2. Navigate to **Manage** → **Access (IAM)** → **API keys** +3. Click **Create an IBM Cloud API key** +4. Provide a name and description +5. Copy and securely store the API key (it will only be shown once) + +!!! warning + Treat your API key as a password. Never commit it to source control or share it publicly. + +### Resource Group +IBM Cloud uses resource groups to organize and manage resources. You will need: + +- **Resource Group Name** - The name of an existing resource group (e.g., `Default`, `mas-development`) +- **Permissions** - Ensure you have Editor or Administrator role on the resource group + +To view available resource groups: +```bash +ibmcloud resource groups +``` + +### OpenShift Version Selection +Choose an OpenShift version supported by both ROKS and your target MAS version. ROKS versions use the format `X.Y_openshift`. Refer to the [MAS system requirements](https://www.ibm.com/docs/en/mas-cd/continuous-delivery) for version compatibility. + + +Cluster Configuration +------------------------------------------------------------------------------- +### Worker Node Flavors +ROKS offers various worker node flavors optimized for different workloads. MAS requires a minimum of 3 worker nodes for high availability. We do not recommend running MAS with worker nodes smaller than 8 vCPUs and 32 GB memory. + +To view all available flavors: +```bash +ibmcloud ks flavors --zone +``` + +### GPU Support (Optional) +ROKS supports GPU-enabled worker nodes for AI/ML workloads. GPU configuration includes: + +- **GPU Worker Count** - Number of GPU-enabled workers +- **GPU Workerpool Name** - Identifier for the GPU worker pool +- **GPU Flavor** - GPU-enabled worker flavor (e.g., `gx2.16x128.1v100`) + +!!! tip + GPU workers are only required for MAS applications with AI/ML capabilities like Predict or Visual Inspection. + + +Provisioning Modes +------------------------------------------------------------------------------- + +### Interactive Mode +Interactive mode guides you through the provisioning process with prompts for all configuration options. + +```bash +docker run -ti --rm --pull always quay.io/ibmmas/cli mas provision-roks +``` + +The interactive session will: + +1. Prompt for IBM Cloud API key +2. Request resource group and cluster name +3. Configure OpenShift version +4. Set worker node specifications +5. Optionally configure GPU workers +6. Display a summary and request confirmation + +### Non-Interactive Mode +Non-interactive mode is ideal for automation and CI/CD pipelines. All required parameters must be provided via command-line arguments or environment variables. + +```bash +export IBMCLOUD_APIKEY=your-api-key + +docker run -ti --rm --pull always quay.io/ibmmas/cli mas provision-roks \ + -a $IBMCLOUD_APIKEY \ + -r mas-development \ + -c mas-prod-cluster \ + -v 4.15_openshift \ + --worker-count 3 \ + --worker-flavor b3c.16x64 \ + --worker-zone dal10 \ + --no-confirm +``` + +Command Reference +------------------------------------------------------------------------------- + +### IBM Cloud Credentials +- `-a, --apikey IBMCLOUD_APIKEY` - IBM Cloud API key (required) + +### Cluster Configuration +- `-r, --resource-group IBMCLOUD_RESOURCEGROUP` - IBM Cloud resource group (required) +- `-c, --cluster-name CLUSTER_NAME` - Cluster name (required) +- `-v, --ocp-version OCP_VERSION` - OpenShift version, e.g., `4.15_openshift` (required) + +### Worker Node Configuration +- `--worker-count ROKS_WORKERS` - Number of worker nodes (default: 3) +- `--worker-flavor ROKS_FLAVOR` - Worker node flavor, e.g., `b3c.16x64` (required) +- `--worker-zone ROKS_ZONE` - IBM Cloud zone, e.g., `dal10` (required) + +### GPU Configuration +- `--gpu-worker-count GPU_WORKERS` - Number of GPU worker nodes (optional) +- `--gpu-workerpool-name GPU_WORKERPOOL_NAME` - GPU workerpool name (optional) + +### Other Options +- `--no-confirm` - Skip confirmation prompt +- `-h, --help` - Display help message + + +Post-Provisioning Steps +------------------------------------------------------------------------------- + +### Accessing Your Cluster +After provisioning completes, access your cluster through the IBM Cloud console or CLI. + +#### Using IBM Cloud Console +1. Navigate to [IBM Cloud Kubernetes Service](https://cloud.ibm.com/kubernetes/clusters) +2. Select your cluster +3. Click **OpenShift web console** to access the cluster + +#### Using IBM Cloud CLI +```bash +# Log in to IBM Cloud +ibmcloud login --apikey $IBMCLOUD_APIKEY + +# Set target resource group +ibmcloud target -g mas-production + +# Get cluster configuration +ibmcloud ks cluster config --cluster mas-prod-cluster + +# Verify connection +oc get nodes +``` + +### Verifying Cluster Health +Check that all nodes are ready: + +```bash +oc get nodes +``` + +Verify storage classes are available: + +```bash +oc get storageclass +``` + +Expected storage classes on ROKS: + +- `ibmc-block-gold` - Block storage (RWO) +- `ibmc-file-gold` - File storage (RWX) +- `ibmc-file-gold-gid` - File storage with GID support + +### Configuring Cluster Access +Set up cluster access for your team: + +1. **IAM Policies** - Configure IBM Cloud IAM for user access +2. **RBAC** - Set up Kubernetes RBAC for fine-grained permissions +3. **Service IDs** - Create service IDs for automation + +### Next Steps +With your ROKS cluster provisioned, you can proceed to: + +- [Install MAS](install.md) +- Configure IBM Cloud services integration +- Set up monitoring and logging +- Configure backup and disaster recovery + +!!! warning "ROKS Limitations" + ROKS clusters do not support `ImageDigestMirrorSet` resources, which limits airgap/image mirroring capabilities. For airgap installations, consider using other OpenShift deployment options. diff --git a/docs/guides/restore.md b/docs/guides/restore.md new file mode 100644 index 00000000000..14323bb4e47 --- /dev/null +++ b/docs/guides/restore.md @@ -0,0 +1,651 @@ +# Restore +The MAS restore process uses Tekton pipelines to orchestrate the restoration of MAS instances from backup archives. The restore operation can recover a complete MAS environment or selectively restore components based on your requirements. The restore process provides extensive configuration flexibility, allowing you to modify key settings during restoration such as domain names, SLS/DRO URLs, and storage classes. + +!!! warning + Before you begin + + Be aware of the following versioning considerations for the MAS CLI releases: + + The MAS backup and restore in CLI release v19.0.0 and later contains process, backup archive file and directory changes that are not backward compatible with earlier backup and restore versions. + + Run the backup processes using v19.0.0 or later to ensure that you can successfully run a restore. You cannot run a restore process using v19.0.0 or later from back ups created on an older version. + +**Supported MAS versions** + +- MAS 9.1.x + +Note: MAS 9.0.x (Not supported yet, its in testing) + +**User Permissions Required** + +- `oc` CLI with cluster admin permissions +- `mas` CLI with appropriate permissions +- Access to Tekton pipeline resources + + +Restore Overview +------------------------------------------------------------------------------- +### Restore Components + +The restore process handles the following components: + +- **IBM Operator Catalogs** - Restores catalog source definitions +- **Certificate Manager** - Restores certificate configurations (RedHat only) +- **MongoDB** - Restores MongoDB instance with SLS & MAS databases (Community Edition only) +- **Suite License Service (SLS)** - Restores SLS instance with license server data (optional, can use external SLS) +- **MAS Suite Configuration** - Restores core MAS instance configuration and custom resources +- **Suite-level SLSCfg** - Restores or provides custom Suite-level SLS configuration with optional URL override +- **Suite-level BASCfg/DROCfg** - Restores or provides custom Suite-level DRO/BAS configuration with optional URL override +- **Manage Database** - Optionally restores incluster Db2 database associated with Manage workspace +- **Manage Application** - Optionally restores Manage application namespace resources and persistent volume data +- **Grafana** - Optionally installs Grafana for monitoring (not part of backup) +- **Data Reporter Operator (DRO)** - Optionally installs DRO (not part of backup), when DRO is installed, an auto-generated Suite-level BASCfg CR will be applied automatically. + +### Restore Limitations + +!!! warning + Be aware of the following limitations before performing a restore: + +- **Restoring from S3 or Artifactory Only** - When using the pipeline, the restore process is limited to restoring from S3 or Artifactory. Restoring from a local backup file is not supported yet. +- **MongoDB Community Edition only** - Restore supports only in-cluster MongoDB Community Edition. Restoring to an external or enterprise MongoDB deployment is not supported. +- **Db2 standalone operator only** - The restore process supports only the in-cluster standalone Db2 operator. Other Db2 operator implementations are not included. +- **Db2uInstance not supported, only Db2uCluster** - The restore process does not support Db2uInstance for now. Will be supported in future release. +- **Certificate Manager (RedHat only)** - Certificate Manager restore is supported only for RedHat Certificate Manager. Other implementations are not handled during restore. +- **Same MAS version required** - Restoring a backup to a cluster running a different MAS version may result in incompatibilities. It is strongly recommended to restore to the same MAS version as the backup source. +- **Same MAS Instance ID required** - It is strongly recommended to restore to the same MAS instance ID as the backup source. +- **Manage application only for app restore** - Only the Manage application is supported. Other MAS applications will be supported in future releases. +- **Tekton pipeline dependency** - The restore process requires Tekton pipelines to be available and functional on the target cluster. +- **Target cluster must be pre-provisioned** - The restore process does not provision a new OpenShift cluster. A running, accessible cluster with sufficient resources must already exist. +- **Storage class compatibility** - The target cluster must have compatible storage classes. If storage classes differ from the source cluster, overrides must be explicitly configured. +- **No partial component restore** - Individual components cannot be selectively restored in isolation without running the full pipeline; component selection is configured at pipeline launch time. +- **Manual Certificate Management Restriction:** Certificates and secrets from backups will be restored. However, changing the domain during the restoration process will cause issues with manual certificates/secrets, and manual updates of certificates and secrets are required. +- **Domain changes require DNS updates** - If restoring with a domain change, DNS records and TLS certificates must be updated manually outside of the restore process. +- **Single MAS instance per restore** - Each restore operation targets a single MAS instance. Restoring multiple instances requires separate restore runs. +- **Grafana and DRO are not restored from backup** - Grafana and DRO are optionally installed fresh during restore; their previous configurations are not recovered from the backup archive. However, Suite-level BASCFG CR resource is backed up and can be restored. +- **No support for CP4D** - The restore process does not support restoring CP4D environments. + +!!! tip + We are working on reducing the limitations of the restore process and will be adding new capabilties and support for other MAS applications in future releases. + +### Configuration Flexibility + +The restore process supports several configuration overrides to adapt the restored environment to new infrastructure: + +- **Domain Configuration** - Change the MAS domain in the Suite CR during restore +- **SLS Configuration** - Restore Suite-level SLSCfg from backup or provide custom configuration file, with optional SLS URL override +- **DRO/BAS Configuration** - Restore Suite-level BASCfg from backup or provide custom configuration file, with optional DRO URL override +- **Storage Class Override** - Override storage classes for all components (MongoDB, Manage app, Manage DB) when restoring to clusters with different storage providers +- **SLS Domain Override** - Change the SLS domain used in the License Service CR +- **Backup Download** - Download backup archives from S3 or Artifactory before restore (useful for cross-cluster restores) + +### Backup Archive Management + +The restore process can work with backup archives in multiple ways: + +- **Local Backup** - Restore from backup archives already present in the cluster +- **S3 Download** - Download backup archives from S3-compatible storage before restore +- **Artifactory Download** - Download backup archives from Artifactory (development mode only) +- **Custom Archive Names** - Support for custom backup archive naming conventions +- **Automatic Cleanup** - Optional cleanup of downloaded archives after successful restore + +When downloading from S3 or Artifactory, the `download_backup_archive` role selectively downloads only the archives required for the restore operation. The following archive selection parameters control which archives are downloaded: + +| Parameter | Default | Description | +|-----------|---------|-------------| +| `include_mongo_archive` | `false` | Download the Mongo backup archive | +| `include_sls_archive` | `false` | Download the SLS backup archive | +| `include_manage_db_archive` | `false` | Download the Manage Db2 database backup archive | +| `include_manage_app_archive` | `false` | Download the Manage application backup archive | + +These parameters are automatically set by the restore pipeline based on the restore configuration (e.g. `--restore-manage-app`, `--restore-manage-db`, `--include-sls`), so you do not need to set them manually when using the `mas restore` command. + +### Ansible DevOps Integration + +The `mas restore` command launches a Tekton pipeline that executes the following Ansible roles from the [IBM MAS DevOps Collection](https://ibm-mas.github.io/ansible-devops/): + +- [`ibm.mas_devops.ibm_catalogs`](https://ibm-mas.github.io/ansible-devops/roles/ibm_catalogs/) - Restores IBM Operator Catalog definitions +- [`ibm.mas_devops.cert_manager`](https://ibm-mas.github.io/ansible-devops/roles/cert_manager/) - Restores Certificate Manager configurations +- [`ibm.mas_devops.mongodb`](https://ibm-mas.github.io/ansible-devops/roles/mongodb/) - Restores MongoDB Community Edition instance and database +- [`ibm.mas_devops.sls`](https://ibm-mas.github.io/ansible-devops/roles/sls/) - Restores Suite License Service data +- [`ibm.mas_devops.suite_restore`](https://ibm-mas.github.io/ansible-devops/roles/suite_restore/) - Restores MAS Core configuration +- [`ibm.mas_devops.db2`](https://ibm-mas.github.io/ansible-devops/roles/db2/) - Restores Db2u instance and database +- [`ibm.mas_devops.suite_app_restore`](https://ibm-mas.github.io/ansible-devops/roles/suite_app_restore/) - Restores supported MAS Application configuration +- [`ibm.mas_devops.grafana`](https://ibm-mas.github.io/ansible-devops/roles/grafana/) - Installs Grafana (optional) +- [`ibm.mas_devops.dro`](https://ibm-mas.github.io/ansible-devops/roles/dro/) - Installs Data Reporter Operator (optional) + + +Restore Modes +------------------------------------------------------------------------------- + +### Interactive Mode + +Interactive mode guides you through the restore process with prompts for all required configuration. This is the recommended approach for manual restores. + +```bash +docker run -ti --rm quay.io/ibmmas/cli mas restore +``` + +The interactive session will: + +1. Prompt for OpenShift cluster connection +2. Request MAS instance ID (must match backup) +3. Request backup version to restore +4. Configure MongoDB storage class override +5. Configure Grafana installation +6. Configure SLS restoration +7. Configure DRO installation +8. Configure MAS domain settings +9. Configure SLS and DRO configuration options +10. Configure Manage application restore +11. Configure Manage Db2 restore +12. Request backup storage size +13. Offer optional download from S3 or Artifactory + +### Non-Interactive Mode + +Non-interactive mode is ideal for automation, scheduled restores, and CI/CD pipelines. All required parameters must be provided via command-line arguments. + +```bash +docker run -ti --rm quay.io/ibmmas/cli mas restore \ + --instance-id inst1 \ + --restore-version 20260117-191701 \ + --no-confirm +``` + + +Restore Process Details +------------------------------------------------------------------------------- + +### Pipeline Execution + +When you run `mas restore`, the following occurs: + +1. **Validation** - Verifies cluster connectivity and prerequisites +2. **Namespace Preparation** - Creates/updates `mas-{instance-id}-pipelines` namespace +3. **OpenShift Pipelines** - Validates or installs OpenShift Pipelines Operator +4. **PVC Creation** - Provisions persistent volume for backup storage +5. **Tekton Pipeline Launch** - Submits PipelineRun with configured parameters +6. **Pre-Restore Check** - Validates cluster readiness +7. **Download** (optional) - Downloads backup archive from S3 or Artifactory +8. **Component Restore** - Executes restore tasks in sequence: + - IBM Catalogs restore + - Certificate Manager restore + - Grafana installation (if enabled) + - MongoDB restore (with optional storage class override) + - SLS restore (if included) + - DRO installation (if enabled) +9. **Suite Restore** - Restores MAS core configuration with optional domain/URL overrides +10. **Manage Application Restore** (if enabled) - Restores Manage application and database +11. **Post-Restore Verification** - Validates restored MAS instance +12. **Workspace Cleanup** (optional, default: enabled) - Cleans backup and config workspaces + +### Monitoring Progress + +After launching the restore, a URL to the Tekton PipelineRun is displayed: + +``` +View progress: + https://console-openshift-console.apps.cluster.example.com/k8s/ns/mas-inst1-pipelines/tekton.dev~v1beta1~PipelineRun/mas-restore-20260117-191701-YYMMDD-HHMM +``` + +Use this URL to: + +- Monitor real-time restore progress +- View logs from individual restore tasks +- Troubleshoot any failures +- Verify successful completion + +### Configuration Flexibility + +The restore process provides several options for handling configurations: + +#### MAS Domain Configuration +- **From Backup** (default) - Uses the domain stored in the Suite backup +- **Override** - Specify `--mas-domain-restore` to change the domain during restore + +#### SLS Configuration +- **From Backup** (default) - Restores SLSCfg from backup with `--include-slscfg-from-backup` +- **Custom File** - Use `--exclude-slscfg-from-backup` and provide `--sls-cfg-file` +- **Change URL** - Use `--sls-url-restore` to modify the SLS URL while keeping other configuration + +#### DRO Configuration +- **From Backup** (default) - Restores BASCfg from backup with `--include-drocfg-from-backup` +- **Custom File** - Use `--exclude-drocfg-from-backup` and provide `--dro-cfg-file` +- **Change URL** - Use `--dro-url-restore` to modify the DRO URL while keeping other configuration + + +Restore Scenarios - Non-Interactive Mode +------------------------------------------------------------------------------- + +### Scenario 1: Basic Restore from Local Backup + +**Environment:** +- Backup archive already present in the cluster PVC +- Standard restore with all defaults + +**Restore Command:** +```bash +mas restore \ + --instance-id inst1 \ + --restore-version 20260117-191701 \ + --no-confirm +``` + +### Scenario 2: Restore with S3 Download + +**Environment:** +- Backup stored in AWS S3 +- Need to download before restore + +**Restore Command:** +```bash +mas restore \ + --instance-id inst1 \ + --restore-version 20260117-191701 \ + --download-backup \ + --aws-access-key-id AKIAIOSFODNN7EXAMPLE \ #pragma: allowlist secret + --aws-secret-access-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY \ #pragma: allowlist secret + --s3-bucket-name mas-backups-prod \ + --s3-region us-east-1 \ + --no-confirm +``` + +### Scenario 3: Restore with Domain Change + +**Environment:** +- Restoring to a different cluster with new domain +- Need to update MAS domain + +**Restore Command:** +```bash +mas restore \ + --instance-id inst1 \ + --restore-version 20260117-191701 \ + --mas-domain-restore new-cluster.example.com \ + --no-confirm +``` + +### Scenario 4: Restore with External SLS + +**Environment:** +- Using external SLS instance +- Skip SLS restore but provide custom SLS configuration + +**Restore Command:** +```bash +mas restore \ + --instance-id inst1 \ + --restore-version 20260117-191701 \ + --exclude-sls \ + --exclude-slscfg-from-backup \ + --sls-cfg-file /path/to/custom-sls-config.yaml \ + --no-confirm +``` + +### Scenario 5: Restore with SLS URL Override + +**Environment:** +- Restore SLS from backup but change the URL +- SLS moved to different endpoint + +**Restore Command:** +```bash +mas restore \ + --instance-id inst1 \ + --restore-version 20260117-191701 \ + --include-sls \ + --include-slscfg-from-backup \ + --sls-url-restore https://new-sls.example.com \ + --no-confirm +``` + +### Scenario 6: Restore with DRO Installation + +**Environment:** +- Install new DRO instance during restore +- Provide DRO configuration details + +**Restore Command:** +```bash +mas restore \ + --instance-id inst1 \ + --restore-version 20260117-191701 \ + --include-dro \ + --ibm-entitlement-key YOUR_ENTITLEMENT_KEY \ #pragma: allowlist secret + --contact-email admin@example.com \ + --contact-firstname John \ + --contact-lastname Doe \ + --dro-namespace redhat-marketplace \ + --no-confirm +``` + +### Scenario 7: Restore Without Grafana + +**Environment:** +- Skip Grafana installation +- Monitoring not required + +**Restore Command:** +```bash +mas restore \ + --instance-id inst1 \ + --restore-version 20260117-191701 \ + --exclude-grafana \ + --no-confirm +``` + +### Scenario 8: Complete Restore with All Options + +**Environment:** +- Download from S3 +- Change domain and SLS URL +- Install DRO and Grafana +- Custom storage size + +**Restore Command:** +```bash +mas restore \ + --instance-id inst1 \ + --restore-version 20260117-191701 \ + --backup-storage-size 100Gi \ + --mas-domain-restore new-cluster.example.com \ + --include-sls \ + --include-slscfg-from-backup \ + --sls-url-restore https://new-sls.example.com \ + --include-drocfg-from-backup \ + --dro-url-restore https://new-dro.example.com \ + --include-grafana \ + --include-dro \ + --ibm-entitlement-key YOUR_ENTITLEMENT_KEY \ #pragma: allowlist secret + --contact-email admin@example.com \ + --contact-firstname John \ + --contact-lastname Doe \ + --dro-namespace redhat-marketplace \ + --download-backup \ + --aws-access-key-id AKIAIOSFODNN7EXAMPLE \ #pragma: allowlist secret + --aws-secret-access-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY \ #pragma: allowlist secret + --s3-bucket-name mas-backups-prod \ + --s3-region us-east-1 \ + --no-confirm +``` + +### Scenario 9: Restore for Troubleshooting (No Cleanup) + +**Environment:** +- Need to inspect workspace contents after restore +- Workspace cleanup disabled + +**Restore Command:** +```bash +mas restore \ + --instance-id inst1 \ + --restore-version 20260117-191701 \ + --no-clean-backup \ + --no-confirm +``` + +!!! note + Use `--no-clean-backup` when you need to inspect the restore workspace contents for troubleshooting. Remember to manually clean up the workspaces later to free up storage. + +### Scenario 10: Emergency Restore (Skip Pre-Check) + +**Environment:** +- Emergency restore scenario +- Skip pre-restore validation for speed + +**Restore Command:** +```bash +mas restore \ + --instance-id inst1 \ + --restore-version 20260117-191701 \ + --skip-pre-check \ + --no-confirm +``` + +!!! warning + Use `--skip-pre-check` only in emergency situations. Pre-restore checks validate cluster readiness and can prevent restore failures. + +### Scenario 11: Restore with MongoDB Storage Class Override + +**Environment:** +- Restoring to a cluster with different storage classes +- Need to override MongoDB storage class + +**Restore Command:** +```bash +mas restore \ + --instance-id inst1 \ + --restore-version 20260117-191701 \ + --override-mongodb-storageclass \ + --mongodb-storageclass-name custom-rwo-storage \ + --no-confirm +``` + +### Scenario 12: Restore with Manage Application + +**Environment:** +- Need to restore Manage application in addition to MAS Suite +- Restore Manage namespace resources and persistent volume data + +**Restore Command:** +```bash +mas restore \ + --instance-id inst1 \ + --restore-version 20260117-191701 \ + --restore-manage-app \ + --no-confirm +``` + +### Scenario 13: Restore with Manage Application and Database + +**Environment:** +- Restore both Manage application and its incluster Db2 database +- Complete Manage workspace restoration + +**Restore Command:** +```bash +mas restore \ + --instance-id inst1 \ + --restore-version 20260117-191701 \ + --restore-manage-app \ + --restore-manage-db \ + --no-confirm +``` + +!!! warning + Manage database restore is an offline operation. The Manage application will be unavailable during the restore process. + +### Scenario 14: Restore Manage with Custom Storage Classes + +**Environment:** +- Restoring to a cluster with different storage infrastructure +- Need to override storage classes for both Manage app and Db2 + +**Restore Command:** +```bash +mas restore \ + --instance-id inst1 \ + --restore-version 20260117-191701 \ + --restore-manage-app \ + --restore-manage-db \ + --override-manage-app-storageclass \ + --manage-app-storage-class-rwx custom-rwx-storage \ + --manage-app-storage-class-rwo custom-rwo-storage \ + --override-manage-db-storageclass \ + --manage-db-storage-class-rwx custom-rwx-storage \ + --manage-db-storage-class-rwo custom-rwo-storage \ + --no-confirm +``` + +!!! note + The Manage Db2 storage class override now uses a single ReadWriteMany (`--manage-db-storage-class-rwx`) and ReadWriteOnce (`--manage-db-storage-class-rwo`) storage class, applied across all Db2 persistent volumes based on the access modes. The previous per-volume flags (`--manage-db-meta-storage-class`, `--manage-db-data-storage-class`, `--manage-db-backup-storage-class`, `--manage-db-logs-storage-class`, `--manage-db-temp-storage-class`) have been removed. + +### Scenario 15: Complete Restore with MongoDB Override and Manage + +**Environment:** +- Comprehensive restore with all new features +- Override MongoDB storage class +- Restore Manage application and database +- Download from S3 + +**Restore Command:** +```bash +mas restore \ + --instance-id inst1 \ + --restore-version 20260117-191701 \ + --backup-storage-size 100Gi \ + --override-mongodb-storageclass \ + --mongodb-storageclass-name custom-rwo-storage \ + --restore-manage-app \ + --restore-manage-db \ + --override-manage-db-storageclass \ + --manage-db-storage-class-rwx custom-rwx-storage \ + --manage-db-storage-class-rwo custom-rwo-storage \ + --download-backup \ + --aws-access-key-id AKIAIOSFODNN7EXAMPLE \ #pragma: allowlist secret + --aws-secret-access-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY \ #pragma: allowlist secret + --s3-bucket-name mas-backups-prod \ + --s3-region us-east-1 \ + --no-confirm +``` + + +Restore Best Practices +------------------------------------------------------------------------------- + +### Pre-Restore Checklist + +1. **Verify Backup Integrity** - Ensure backup archives are complete and accessible +2. **Check Cluster Resources** - Verify sufficient CPU, memory, and storage +3. **Review Target Environment** - Confirm cluster version and configuration compatibility +4. **Plan Domain Changes** - Determine if domain or URL changes are needed +5. **Prepare External Services** - Ensure external SLS/DRO are accessible if used +6. **Review Storage Classes** - Identify if MongoDB or Manage storage class overrides are needed +7. **Plan Manage Restore** - Determine if Manage application and database should be restored +8. **Document Configuration** - Record any custom configurations or overrides + +### During Restore + +1. **Monitor Pipeline** - Watch the Tekton PipelineRun for any issues +2. **Check Logs** - Review task logs if any failures occur +3. **Verify Components** - Ensure each component restores successfully +4. **Note Timing** - Track restore duration for future planning + +### Post-Restore Verification + +1. **Validate Suite Status** - Confirm MAS Suite CR is ready +2. **Check Application Access** - Verify MAS applications are accessible +3. **Test Integrations** - Validate connections to databases and external services +4. **Verify MongoDB** - Confirm MongoDB is running with correct storage class if overridden +5. **Validate Manage Application** - If restored, verify Manage application is accessible and functional +6. **Check Manage Database** - If restored, confirm Db2 database is running with correct storage classes +7. **Review Configurations** - Confirm all configurations are correct +8. **Update DNS** - Update DNS records if domain changed +9. **Test Functionality** - Perform smoke tests on critical functions + +### Common Restore Scenarios + +#### Disaster Recovery +- Use latest backup from off-site storage +- May require domain and URL changes +- Verify all external dependencies are available +- Consider MongoDB storage class override if infrastructure changed +- Include Manage application and database restore if needed + +#### Cluster Migration +- Download backup from source cluster storage +- Change domain to match new cluster +- Update SLS and DRO URLs if needed +- Override MongoDB and Manage storage classes for different infrastructure +- Verify network connectivity and routes +- Plan for Manage database downtime during restore + +#### Environment Cloning +- Use production backup for dev/test +- Change domain to avoid conflicts +- Consider using external SLS to share licenses +- May exclude DRO for non-production environments +- Override storage classes to use lower-cost storage in non-production +- Optionally restore Manage application for testing + + +Restore Troubleshooting +------------------------------------------------------------------------------- + +### Common Restore Issues + +**Issue: "Backup archive not found"** + +- Verify backup archive exists in PVC or download location +- Check backup version matches the archive name +- Ensure download credentials are correct if downloading from S3/Artifactory + +**Issue: "Pre-restore check failed"** + +- Review cluster resource availability +- Check OpenShift version compatibility +- Verify required operators are available +- Use `--skip-pre-check` only if necessary + +**Issue: "MongoDB restore failed"** + +- Verify MongoDB namespace and instance name match backup +- Ensure sufficient storage for MongoDB data +- Check MongoDB operator is installed and ready +- If using storage class override, verify the storage class exists and is accessible +- Ensure the specified storage class supports ReadWriteOnce access mode + +**Issue: "SLS restore failed"** + +- Verify SLS namespace is correct +- Check if using `--include-sls` or `--exclude-sls` appropriately +- Ensure SLS configuration file is valid if using custom config + +**Issue: "Suite restore failed with domain mismatch"** + +- Use `--mas-domain-restore` to override domain from backup +- Verify DNS records are updated for new domain +- Check certificate configurations match new domain + +**Issue: "DRO installation failed"** + +- Verify IBM entitlement key is valid +- Check DRO namespace has sufficient permissions +- Ensure contact information is provided correctly + +**Issue: "Download from S3 failed"** + +- Verify AWS credentials are correct +- Check S3 bucket exists and is accessible +- Verify network connectivity to AWS +- Ensure IAM permissions allow GetObject operations + +**Issue: "Configuration file not found"** +**Issue: "Manage application restore failed"** + +- Verify Manage workspace exists in the backup +- Ensure sufficient storage for Manage application persistent volumes +- Check that storage class overrides (if specified) are valid and accessible +- Verify both ReadWriteMany and ReadWriteOnce storage classes are available if using overrides +- Review Manage namespace for any conflicting resources + +**Issue: "Manage Db2 database restore failed"** + +- Verify Db2 instance exists in the backup +- Ensure sufficient storage for all Db2 persistent volumes (meta, data, backup, logs, temp) +- Check that all specified storage classes exist and support required access modes +- Verify Db2 operator is installed and ready +- Review Db2 pod logs for specific error messages +- Note: Db2 restore is an offline operation - ensure no active connections during restore + +**Issue: "Storage class not found during restore"** + +- Verify the specified storage class exists in the target cluster: `oc get storageclass` +- Check storage class supports the required access mode (RWO or RWX) +- If using cluster defaults, ensure default storage classes are configured +- Review storage class provisioner compatibility with the cluster infrastructure + + +- Verify custom config file paths are correct +- Ensure files are accessible from the CLI container +- Check file format is valid YAML diff --git a/docs/guides/uninstall.md b/docs/guides/uninstall.md index beeb92acd78..c270bbcb5d1 100644 --- a/docs/guides/uninstall.md +++ b/docs/guides/uninstall.md @@ -1,29 +1,103 @@ Uninstall =============================================================================== -Uninstall Overview +Overview ------------------------------------------------------------------------------- -Uninstall will remove an entire MAS installation from a cluster, including all installed applications. +The MAS CLI provides automated uninstallation of Maximo Application Suite from OpenShift clusters. The uninstall process removes MAS instances, applications, and optionally their dependencies, providing a clean removal or preparation for reinstallation. -1 Uninstall Maximo Application Suite +!!! tip + For production environments, always test the uninstall process in a non-production environment first to identify potential issues and estimate timing. + +This guide covers the complete uninstallation process, including MAS instances, applications, and dependency management. + +!!! warning "Data Loss" + Uninstalling MAS will permanently delete all MAS data, configurations, and applications. Ensure you have backups before proceeding. Consider using the [backup functionality](backup.md) before uninstalling. + + +Understanding MAS Uninstallation ------------------------------------------------------------------------------- -Run `mas uninstall` and select the MAS installation instance that you want to uninstall. -```bash -mas uninstall -``` +### What Gets Uninstalled +The uninstall process removes: + +- **MAS Core** - Suite operator and core services +- **MAS Applications** - All installed applications (Manage, Monitor, IoT, etc.) +- **Application Data** - Persistent volumes and databases +- **Configurations** - Custom resources and configurations +- **Namespaces** - MAS instance namespaces + +### Optional Dependency Removal +You can optionally remove shared dependencies: + +- **Certificate Manager** - TLS certificate management +- **IBM Common Services** - Shared IBM services +- **Grafana** - Monitoring and dashboards +- **MongoDB** - MAS configuration database +- **Suite License Service (SLS)** - License management +- **Data Reporter Operator (DRO)** - Usage reporting +- **IBM Operator Catalog** - IBM operator catalog source + +!!! warning "Shared Dependencies" + Be cautious when removing dependencies in multi-instance or shared cluster environments. Removing shared dependencies can impact other applications and MAS instances. + + +Uninstallation Process +------------------------------------------------------------------------------- + +### How Uninstall Works +The `mas uninstall` command performs the following steps: + +1. **Detects MAS Instances** - Identifies installed MAS instances +2. **Validates Selection** - Confirms instance to uninstall +3. **Removes Applications** - Uninstalls all MAS applications +4. **Removes Core** - Uninstalls MAS core operator +5. **Cleans Namespaces** - Deletes MAS namespaces +6. **Removes Dependencies** - Optionally removes shared dependencies +7. **Cleans Resources** - Removes cluster-scoped resources -The command can also be ran non-interactive. + +### Interactive Mode +Interactive mode guides you through the uninstallation process with prompts for all options. ```bash -mas uninstall -i @@MAS_INSTANCE@@ --no-confirm +docker run -ti --rm --pull always quay.io/ibmmas/cli mas uninstall ``` -The command can be ran in a prebuilt CLI docker container. +The interactive session will: + +1. Prompt for OpenShift cluster connection (if not connected) +2. Display detected MAS instances +3. Request instance selection for uninstallation +4. Ask whether to remove dependencies +5. Display uninstallation summary +6. Request confirmation before proceeding + +### Non-Interactive Mode +Non-interactive mode is ideal for automation and scripting. All required parameters must be provided via command-line arguments. ```bash -docker run -ti --rm --pull always quay.io/ibmmas/cli mas uninstall +docker run -ti --rm --pull always quay.io/ibmmas/cli mas uninstall \ + --mas-instance-id inst1 \ + --no-confirm ``` -Note: If you are not already connected to an OpenShift cluster you will be prompted to provide the server URL & token, and whether to verify the server certificate or not, If you are already connected to a cluster you will be given the option to change to another cluster. +Command Reference +------------------------------------------------------------------------------- + +### MAS Instance Selection +- `--mas-instance-id MAS_INSTANCE_ID` - MAS instance ID to uninstall (required in non-interactive mode) + +### Dependency Removal Options +- `--uninstall-all-deps` - Remove all MAS-related dependencies +- `--uninstall-cert-manager` - Remove Certificate Manager +- `--uninstall-common-services` - Remove IBM Common Services +- `--uninstall-grafana` - Remove Grafana +- `--uninstall-ibm-catalog` - Remove IBM Operator Catalog (ibm-operator-catalog) +- `--uninstall-mongodb` - Remove MongoDB +- `--uninstall-sls` - Remove Suite License Service +- `--uninstall-dro` - Remove Data Reporter Operator + +### Other Options +- `--no-confirm` - Skip confirmation prompt +- `-h, --help` - Display help message diff --git a/docs/index.md b/docs/index.md index a507894fa30..75a2b6a54fb 100644 --- a/docs/index.md +++ b/docs/index.md @@ -44,22 +44,22 @@ Function support ------------------------------------------------------------------------------- Not all functions supported in the container image are available in the standalone CLI binary: -| CLI Function | Image | Binary | -| ---------------------------------------------------------- | :------: | :------: | -| [install](guides/install.md) | ✓ | ✓ | -| [aiservice-install](guides/aiservice-install.md) | ✓ | ✓ | -| [update](guides/update.md) | ✓ | ✓ | -| [upgrade](guides/upgrade.md) | ✓ | ✓ | -| [uninstall](commands/uninstall.md) | ✓ | ✓ | -| [must-gather](commands/must-gather.md) | ✓ | ✕ | -| [configure-airgap](commands/configure-airgap.md) | ✓ | ✕ | -| [mirror-images](guides/image-mirroring.md) | ✓ | ✕ | -| [mirror-redhat-images](commands/mirror-redhat-images.md) | ✓ | ✕ | -| [setup-registry](commands/setup-registry.md) | ✓ | ✕ | -| [teardown-registry](commands/teardown-registry.md) | ✓ | ✕ | -| [provision-fyre](commands/provision-fyre.md) | ✓ | ✕ | -| [provision-roks](commands/provision-roks.md) | ✓ | ✕ | -| [provision-rosa](commands/provision-rosa.md) | ✓ | ✕ | -| [configtool-oidc](commands/configtool-oidc.md) | ✓ | ✕ | -| [backup](commands/backup.md) | ✓ | ✓ | -| [restore](commands/restore.md) | ✓ | ✓ | +| CLI Function | Image | Binary | +| ------------------------------------------------------------------- | :------: | :------: | +| [install](guides/install.md) | ✓ | ✓ | +| [aiservice-install](guides/aiservice-install.md) | ✓ | ✓ | +| [update](guides/update.md) | ✓ | ✓ | +| [upgrade](guides/upgrade.md) | ✓ | ✓ | +| [uninstall](guides/uninstall.md) | ✓ | ✓ | +| [must-gather](commands/must-gather.md) | ✓ | ✕ | +| [configure-airgap](guides/configure-airgap.md) | ✓ | ✕ | +| [mirror-images](guides/image-mirroring.md) | ✓ | ✕ | +| [mirror-redhat-images](commands/mirror-redhat-images.md) | ✓ | ✕ | +| [setup-registry](guides/private-registry.md#registry-removal) | ✓ | ✕ | +| [teardown-registry](guides/private-registry.md#registry-deployment) | ✓ | ✕ | +| [provision-aws](guides/provision-aws.md) | ✓ | ✕ | +| [provision-fyre](guides/provision-fyre.md) | ✓ | ✕ | +| [provision-roks](guides/provision-roks.md) | ✓ | ✕ | +| [configtool-oidc](commands/configtool-oidc.md) | ✓ | ✕ | +| [backup](guides/backup.md) | ✓ | ✓ | +| [restore](guides/restore.md) | ✓ | ✓ | diff --git a/mkdocs.yml b/mkdocs.yml index e664f254bea..9573088180c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -8,32 +8,34 @@ repo_url: https://github.com/ibm-mas/cli edit_uri: blob/master/docs/ nav: - - "Guides": - - "Image Mirroring": guides/image-mirroring.md - - "Image Validation": guides/image-validation.md + - "OpenShift Management": + - "IBM Cloud ROKS": guides/provision-roks.md + - "AWS (IPI)": guides/provision-aws.md + - "IBM DevIT FYRE": guides/provision-fyre.md + - "Airgap Configuration": guides/configure-airgap.md + - "Image Mirroring": + - "Private Registry": guides/private-registry.md + - "Image Mirroring (IBM)": guides/image-mirroring.md + - "Image Mirroring (Red Hat)": commands/mirror-redhat-images.md + - "Install and Configure": - "Install": guides/install.md - - "AI Service Standalone Install": guides/aiservice-install.md + - "Uninstall": guides/uninstall.md + - "OIDC Config Tool": commands/configtool-oidc.md + - "AI Service Install": guides/aiservice-install.md + - "Update and Upgrade": - "Update": guides/update.md - "Upgrade": guides/upgrade.md - - "Uninstall": guides/uninstall.md - - "Backup and Restore": guides/backup-restore.md + - "Backup and Restore": + - "Backup": guides/backup.md + - "Restore": guides/restore.md + - "Troubleshooting": + - "Debug": commands/debug.md + - "Must-Gather": commands/must-gather.md - "Examples": - "EAM Migration": examples/eam-migration.md - "Mirror Db2 Images": examples/mirror-db2.md - "Minimal RBAC": examples/minimal-rbac.md - - "Command Reference": - - "uninstall": commands/uninstall.md - - "must-gather": commands/must-gather.md - - "configure-airgap": commands/configure-airgap.md - - "mirror-redhat-images": commands/mirror-redhat-images.md - - "setup-registry": commands/setup-registry.md - - "teardown-registry": commands/teardown-registry.md - - "provision-fyre": commands/provision-fyre.md - - "provision-roks": commands/provision-roks.md - - "provision-rosa": commands/provision-rosa.md - - "configtool-oidc": commands/configtool-oidc.md - - "backup": commands/backup.md - - "restore": commands/restore.md + - "Image Validation": guides/image-validation.md - "Operator Catalogs": - "Overview": catalogs/index.md - "Apr 30 2026": catalogs/v9-260430-amd64.md @@ -87,12 +89,23 @@ plugins: - redirects: redirect_maps: "guides/architecture/core.md": "https://www.ibm.com/docs/en/mas-cd/continuous-delivery?topic=reference-maximo-application-suite-core-services" + "guides/backup-and-restore.md": "guides/backup.md" "guides/mas-pods-explained.md": "https://www.ibm.com/docs/en/mas-cd/continuous-delivery?topic=reference-maximo-application-suite-pod-details" "guides/choosing-the-right-catalog.md": "catalogs/index.md" "commands/mirror-images.md": "guides/image-mirroring.md" "commands/install.md": "guides/install.md" "commands/update.md": "guides/update.md" "commands/upgrade.md": "guides/upgrade.md" + "commands/provision-fyre.md": "guides/provision-fyre.md" + "commands/provision-roks.md": "guides/provision-roks.md" + "commands/provision-rosa.md": "guides/provision-roks.md" + "commands/provision-aws.md": "guides/provision-aws.md" + "commands/configure-airgap.md": "guides/configure-airgap.md" + "commands/setup-registry.md": "guides/private-registry.md" + "commands/teardown-registry.md": "guides/private-registry.md" + "commands/uninstall.md": "guides/uninstall.md" + "commands/backup.md": "guides/backup.md" + "commands/restore.md": "guides/restore.md" - glightbox: shadow: true caption_position: bottom