diff --git a/.secrets.baseline b/.secrets.baseline index f6ca12d1b7c..cfe8390329a 100644 --- a/.secrets.baseline +++ b/.secrets.baseline @@ -3,7 +3,7 @@ "files": "^.secrets.baseline$", "lines": null }, - "generated_at": "2024-12-16T05:50:45Z", + "generated_at": "2024-12-16T12:18:06Z", "plugins_used": [ { "name": "AWSKeyDetector" @@ -102,7 +102,17 @@ "hashed_secret": "b60d121b438a380c343d5ec3c2037564b82ffef3", "is_secret": false, "is_verified": false, - "line_number": 22, + "line_number": 46, + "type": "Secret Keyword", + "verified_result": null + } + ], + "docs/guides/install.md": [ + { + "hashed_secret": "b60d121b438a380c343d5ec3c2037564b82ffef3", + "is_secret": false, + "is_verified": false, + "line_number": 237, "type": "Secret Keyword", "verified_result": null } diff --git a/Makefile b/Makefile index 02ee0a48c3d..a452859dcea 100644 --- a/Makefile +++ b/Makefile @@ -16,7 +16,7 @@ python-cli: cp python/dist/mas_cli-100.0.0.tar.gz image/cli/install/mas_cli.tar.gz python-devops: - cd ../python-devops && python -m build + cd ../python-devops && make build cp ../python-devops/dist/mas_devops-100.0.0.tar.gz image/cli/install/mas_devops.tar.gz python: python-devops python-cli diff --git a/build/bin/build-docs.sh b/build/bin/build-docs.sh index af9c4b1021a..f1c4efa8cb7 100644 --- a/build/bin/build-docs.sh +++ b/build/bin/build-docs.sh @@ -12,4 +12,4 @@ find docs -type f -name '*.md' -exec sed -i \ {} \; python -m pip install -q mkdocs mkdocs-carbon mkdocs-glightbox mkdocs-redirects -mkdocs build --verbose --clean --strict +mkdocs build --clean --strict diff --git a/docs/catalogs/index.md b/docs/catalogs/index.md index 55f87e190a3..f2ee955788a 100644 --- a/docs/catalogs/index.md +++ b/docs/catalogs/index.md @@ -304,7 +304,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](../commands/mirror-images.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 **ImageContentSourcePolicy** 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](../commands/configure-airgap.md) function to add the IBM Maximo Application Suite **ImageContentSourcePolicy** to your cluster before starting the installation. ### Dynamic Catalog diff --git a/docs/commands/install.md b/docs/commands/install.md deleted file mode 100644 index d8ac3d56428..00000000000 --- a/docs/commands/install.md +++ /dev/null @@ -1,659 +0,0 @@ -Install -=============================================================================== - -Usage -------------------------------------------------------------------------------- -For full usage information run `mas install --help` - - -Non-Interactive Install -------------------------------------------------------------------------------- -```bash -docker run -ti --rm -v ~:/mnt/home --pull always quay.io/ibmmas/cli -export ENTITLEMENT_KEY=xxx -mas install -i mas1 -w ws1 -W "My Workspace" -c @@MAS_LATEST_CATALOG@@ --mas-channel @@MAS_LATEST_CHANNEL@@ \ - --ibm-entitlement-key $ENTITLEMENT_KEY \ - --license-id xxxxxxxxxxxx --license-file /mnt/home/entitlement.lic \ - --uds-email myemail@email.com --uds-firstname John --uds-lastname Barnes \ - --storage-rwo ibmc-block-gold --storage-rwx ibmc-file-gold-gid \ - --storage-pipeline ibmc-file-gold-gid --storage-accessmode ReadWriteMany \ - --no-confirm \ - --accept-license -``` - - -Interactive Install -------------------------------------------------------------------------------- - -```bash -docker run -ti --rm -v ~:/mnt/home --pull always quay.io/ibmmas/cli -mas install -``` - -!!! important - We will need the `entitlement.lic` file to perform the installation which is why we mount your home directory into the container. If you saved the entitlement file elsewhere, mount that directory instead. - - When prompted you will be able to set license file to `/mnt/home/entitlement.lic` - - -### Connect to OpenShift -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. - -``` -1) Set Target OpenShift Cluster -Server URL: https://c100-e.eu-gb.containers.cloud.ibm.com:32173 -Login Token: ************************************************** -Disable TLS Verify? [y/n] n -``` - -If you are already connected to a cluster you will be given the option to change to another cluster. - -``` -1) Set Target OpenShift Cluster -Already connected to OCP Cluster: - https://console-openshift-console.xarchtest-6f1620198115433da1cac8216c06779b-0000.eu-gb.containers.appdomain.cloud - -Proceed with this cluster? [y/n] -``` - -### Choose a Catalog Source -You will be presented with a table of available catalogs with information about the different releases of MAS available in each. Make the selection using the numbers in the first column. - -``` -2) IBM Maximo Operator Catalog Selection -┌─────┬─────────────────┬───────────┬─────────┬──────────┬────────┬──────────┬───────────┬─────────────┬───────────┬──────────────┬────────────┐ -│ # │ catalog │ release │ core │ assist │ iot │ manage │ monitor │ optimizer │ predict │ inspection │ aibroker │ -├─────┼─────────────────┼───────────┼─────────┼──────────┼────────┼──────────┼───────────┼─────────────┼───────────┼──────────────┼────────────┤ -│ 1 │ v9-241003-amd64 │ 9.0.x │ 9.0.3 │ 9.0.2 │ 9.0.3 │ 9.0.3 │ 9.0.3 │ 9.0.3 │ 9.0.2 │ 9.0.3 │ 9.0.2 │ -├─────┼─────────────────┼───────────┼─────────┼──────────┼────────┼──────────┼───────────┼─────────────┼───────────┼──────────────┼────────────┤ -│ 2 │ v9-241003-amd64 │ 8.11.x │ 8.11.15 │ 8.8.6 │ 8.8.13 │ 8.7.12 │ 8.11.11 │ 8.5.9 │ 8.9.5 │ 8.9.6 │ │ -├─────┼─────────────────┼───────────┼─────────┼──────────┼────────┼──────────┼───────────┼─────────────┼───────────┼──────────────┼────────────┤ -│ 3 │ v9-241003-amd64 │ 8.10.x │ 8.10.18 │ 8.7.7 │ 8.7.17 │ 8.6.18 │ 8.10.14 │ 8.4.10 │ 8.8.3 │ 8.8.4 │ │ -├─────┼─────────────────┼───────────┼─────────┼──────────┼────────┼──────────┼───────────┼─────────────┼───────────┼──────────────┼────────────┤ -│ 4 │ v9-240827-amd64 │ 9.0.x │ 9.0.2 │ 9.0.2 │ 9.0.2 │ 9.0.2 │ 9.0.2 │ 9.0.2 │ 9.0.1 │ 9.0.2 │ │ -├─────┼─────────────────┼───────────┼─────────┼──────────┼────────┼──────────┼───────────┼─────────────┼───────────┼──────────────┼────────────┤ -│ 5 │ v9-240827-amd64 │ 8.11.x │ 8.11.14 │ 8.8.6 │ 8.8.12 │ 8.7.11 │ 8.11.10 │ 8.5.8 │ 8.9.3 │ 8.9.5 │ │ -├─────┼─────────────────┼───────────┼─────────┼──────────┼────────┼──────────┼───────────┼─────────────┼───────────┼──────────────┼────────────┤ -│ 6 │ v9-240827-amd64 │ 8.10.x │ 8.10.17 │ 8.7.7 │ 8.7.16 │ 8.6.17 │ 8.10.13 │ 8.4.9 │ 8.8.3 │ 8.8.4 │ │ -├─────┼─────────────────┼───────────┼─────────┼──────────┼────────┼──────────┼───────────┼─────────────┼───────────┼──────────────┼────────────┤ -│ 7 │ v9-240730-amd64 │ 9.0.x │ 9.0.1 │ 9.0.1 │ 9.0.1 │ 9.0.1 │ 9.0.1 │ 9.0.1 │ 9.0.0 │ 9.0.0 │ │ -├─────┼─────────────────┼───────────┼─────────┼──────────┼────────┼──────────┼───────────┼─────────────┼───────────┼──────────────┼────────────┤ -│ 8 │ v9-240730-amd64 │ 8.11.x │ 8.11.13 │ 8.8.5 │ 8.8.11 │ 8.7.10 │ 8.11.9 │ 8.5.7 │ 8.9.3 │ 8.9.4 │ │ -├─────┼─────────────────┼───────────┼─────────┼──────────┼────────┼──────────┼───────────┼─────────────┼───────────┼──────────────┼────────────┤ -│ 9 │ v9-240730-amd64 │ 8.10.x │ 8.10.16 │ 8.7.6 │ 8.7.15 │ 8.6.16 │ 8.10.12 │ 8.4.8 │ 8.8.3 │ 8.8.4 │ │ -└─────┴─────────────────┴───────────┴─────────┴──────────┴────────┴──────────┴───────────┴─────────────┴───────────┴──────────────┴────────────┘ -Select catalog and release 1 -``` - -### Accept the License Terms -Confirm that you accept the IBM Maximo Application Suite license terms - -``` -3) License Terms -To continue with the installation, you must accept the license terms: - - https://ibm.biz/MAS90-License - - https://ibm.biz/MaximoIT90-License - - https://ibm.biz/MAXArcGIS90-License -Do you accept the license terms? [y/n] y -``` - -### Select Storage Classes -MAS requires both a `ReadWriteMany` and a `ReadWriteOnce` capable storage class to be available in the cluster. The installer has the ability to recognize certain storage class providers and will default to the most appropriate storage class in these cases: - -- IBMCloud Storage (`ibmc-block-gold` & `ibmc-file-gold-gid`) -- OpenShift Container Storage (`ocs-storagecluster-ceph-rbd` & `ocs-storagecluster-cephfs`) -- External OpenShift Container Storage (`ocs-external-storagecluster-ceph-rbd` & `ocs-external-storagecluster-cephfs`) -- NFS Client (`nfs-client`) -- Azure Managed Storage (`managed-premium` & `azurefiles-premium`) -- AWS Storage (`gp3-cs` & `efs`) - -The names in brackets represent the `ReadWriteOnce` and `ReadWriteMany` class that will be used, in the case of NFS the same storage class will be used for both `ReadWriteOnce` and `ReadWriteMany` volumes. Even when a recognized storage provider is detected you will be provided with the option to select your own storages classes anyway. - -When selecting storage classes you will be presented with a list of available storage classes and must select both a `ReadWriteMany` and a `ReadWriteOnce` storage class. - -``` -4) Configure Storage Class Usage -Maximo Application Suite and it's dependencies require storage classes that support ReadWriteOnce (RWO) and ReadWriteMany (RWX) access modes: - - ReadWriteOnce volumes can be mounted as read-write by multiple pods on a single node. - - ReadWriteMany volumes can be mounted as read-write by multiple pods across many nodes. - -Storage provider auto-detected: IBMCloud ROKS - - Storage class (ReadWriteOnce): ibmc-block-gold - - Storage class (ReadWriteMany): ibmc-file-gold-gid -Use the auto-detected storage classes? [y/n] y -``` - -!!! warning - Unfortunately there is no way for the install to verify that the storage class selected actually supports the appropriate access mode, refer to the documentation from the storage class provider to determine whether your storage class supports `ReadWriteOnce` and/or `ReadWriteMany`. - -### Provide a License File -Provide the location of your license file and your contact information. - -``` -5) Configure Product License -License file /mnt/home/entitlement.lic -Contact e-mail address test@uk.ibm.com -Contact first name David -Contact last name Parker -IBM Data Reporter Operator (DRO) Namespace redhat-marketplace -``` - -### Provide your IBM Entitlement Key -Provide your IBM entitlement key. If you have set the `IBM_ENTITLEMENT_KEY` environment variable then this field will be pre-filled with that value already. - -``` -6) Configure IBM Container Registry -IBM entitlement key ****************************************** -``` - -### Configure your MAS Instance -Provide the basic information about your MAS instance: - -- Instance ID -- Workspace ID -- Workspace Display Name - -``` -7) Configure MAS Instance -Instance ID restrictions: - - Must be 3-12 characters long - - Must only use lowercase letters, numbers, and hypen (-) symbol - - Must start with a lowercase letter - - Must end with a lowercase letter or a number -Instance ID mas1 - -Workspace ID restrictions: - - Must be 3-12 characters long - - Must only use lowercase letters and numbers - - Must start with a lowercase letter -Workspace ID ws1 - -Workspace display name restrictions: - - Must be 3-300 characters long -Workspace name ws1 -``` - -### Choose Operational Mode -The install will default to a production mode installation, but by choosing "y" at the prompt you will be able to install MAS in non-production mode. - -``` -8) Configure Operational Mode -Maximo Application Suite can be installed in a non-production mode for internal development and testing, this setting cannot be changed after installation: - - All applications, add-ons, and solutions have 0 (zero) installation AppPoints in non-production installations. - - These specifications are also visible in the metrics that are shared with IBM and in the product UI. - - 1. Production - 2. Non-Production -Operational Mode 2 -``` - -### Configure Root CA Trust -``` -9) Certificate Authority Trust -By default, Maximo Application Suite is configured to trust well-known certificate authoritories, you can disable this so that it will only trust the CAs that you explicitly define -Trust default CAs? [y/n] y -``` - -### Override the OpenShift Ingress Secret -``` -10) Cluster Ingress Secret Override -In most OpenShift clusters the installation is able to automatically locate the default ingress certificate, however in some configurations it is necessary to manually configure the name of the secret -Unless you see an error during the ocp-verify stage indicating that the secret can not be determined you do not need to set this and can leave the response empty -Cluster ingress certificate secret name -``` - -### Configure Domain & Certificate Management -By default MAS will be installed in a subdomain of your OpenShift clusters domain matching the MAS instance ID that you chose. For example if your OpenShift cluster is `myocp.net` and you are installing MAS with an instance ID of `prod1` then MAS will be installed with a default domain something like `prod1.apps.myocp.net`, depending on the exact network configuration of your cluster. - -If you wish to use a custom domain for the MAS install you can choose to configure this by selecting "n" at the prompt. The install supports DNS integrations for Cloudflare, IBM Cloud Internet Services, AWS Route 53 out of the box and is able to configure a certificate issuer using LetsEncrypt (production or staging) or a self-signed certificate authority per your choices. - -``` -11) Configure Domain & Certificate Management -Configure domain & certificate management? [y/n] n -``` - -### Customize MAS SSO -``` -12) Single Sign-On (SSO) -Many aspects of Maximo Application Suite's Single Sign-On (SSO) can be customized: - - Idle session automatic logout timer - - Session, access token, and refresh token timeouts - - Default identity provider (IDP), and seamless login - - Brower cookie properties -Configure SSO properties? [y/n] n -``` - -### Allow special character in User IDs and Usernames -``` -13) Configure special characters for userID and username -Do you want to allow special characters for user IDs and usernames?? [y/n] n -``` - -### Configure Whether Guided Tours Are Shown -``` -14) Enable Guided Tour -By default, Maximo Application Suite is configured with guided tour, you can disable this if it not required -Enable Guided Tour? [y/n] n -``` - -### Application Selection -Select the applications that you would like to install. Note that some applications cannot be installed unless an application they depend on is also installed: - -- Monitor is only available for install if IoT is selected -- Assist and Predict are only available for install if Monitor is selected - -``` -15) Application Selection -Install IoT? [y/n] n -Install Manage? [y/n] y -Install Assist? [y/n] n -Install Optimizer? [y/n] n -Install Visual Inspection? [y/n] n -Install AI Broker? [y/n] n -``` - -### Application Configuration -``` -16) Configure Maximo Manage -Customize your Manage installation, refer to the product documentation for more information - -16.1) Maximo Manage Components -The default configuration will install Manage with Health enabled, alternatively choose exactly what industry solutions and add-ons will be configured -Select components to enable? [y/n] y - - Asset Configuration Manager? [y/n] n - - Aviation? [y/n] n - - Civil Infrastructure? [y/n] n - - Envizi? [y/n] n - - Health? [y/n] n - - Health, Safety and Environment? [y/n] n - - Maximo IT? [y/n] n - - Nuclear? [y/n] n - - Oil & Gas? [y/n] n - - Connector for Oracle Applications? [y/n] n - - Connector for SAP Application? [y/n] n - - Service Provider? [y/n] n - - Spatial? [y/n] n - - Strategize? [y/n] n - - Transportation? [y/n] n - - Tririga? [y/n] n - - Utilities? [y/n] n - - Workday Applications? [y/n] n - -16.2) Maximo Manage Settings - Server Bundles -Define how you want to configure Manage servers: - - You can have one or multiple Manage servers distributing workload - - Additionally, you can choose to include JMS server for messaging queues - -Configurations: - 1. Deploy the 'all' server pod only (workload is concentrated in just one server pod but consumes less resource) - 2. Deploy the 'all' and 'jms' bundle pods (workload is concentrated in just one server pod and includes jms server) - 3. Deploy the 'mea', 'report', 'ui' and 'cron' bundle pods (workload is distributed across multiple server pods) - 4. Deploy the 'mea', 'report', 'ui', 'cron' and 'jms' bundle pods (workload is distributed across multiple server pods and includes jms server) -Select a server bundle configuration 1 - -16.3) Maximo Manage Settings - Database -Customise the schema, tablespace, indexspace, and encryption settings used by Manage -Customize database settings? [y/n] n - -16.4) Maximo Manage Settings - Customization -Provide a customization archive to be used in the Manage build process -Include customization archive? [y/n] n - -16.5) Maximo Manage Settings - Other -Configure additional settings: - - Demo data - - Base and additional languages - - Server timezone - - Cognos integration (install Cloud Pak for Data) - - Watson Studio Local integration (install Cloud Pak for Data) -Configure Additional Settings? [y/n] n -``` - -### Configure MongoDb -``` -17) Configure MongoDb -Install namespace mongoce -``` - -### Configure Databases -If you have selected one or more applications that require a JDBC datasource (IoT, Manage, Monitor, & Predict) you must choose how to provide that dependency: - -- Use the IBM Db2 Universal Operator -- Provide a JDBC configuration - -If you choose the latter then you will be prompted to select a local directory where the configuration will be staged and requested to provide a display name, the JDBC connection URL, username, password, and whether the endpoint is SSL enabled (if it is then you will also be asked to provide the SSL certificate required to connect to the database). - -!!! tip - If you have already generated the configuration file (manually, or using the install previously) the CLI will detect this and prompt whether you wish to re-use the existing configuration, or generate a new one. - -``` -18) Configure Databases -The installer can setup one or more IBM Db2 instances in your OpenShift cluster for the use of applications that require a JDBC datasource (IoT, Manage, Monitor, & Predict) or you may choose to configure MAS to use an existing database - -18.1) Database Configuration for Maximo Manage -Maximo Manage can be configured to share the system Db2 instance or use it's own dedicated database: - - Use of a shared instance has a significant footprint reduction but is only recommended for development/test/demo installs - - In most production systems you will want to use a dedicated database - - IBM Db2, Oracle Database, & Microsoft SQL Server are all supported database options -Create manage dedicated Db2 instance using the IBM Db2 Universal Operator? [y/n] y -Available Db2 instance types for Manage: - 1. DB2 Warehouse (Default option) - 2. DB2 Online Transactional Processing (OLTP) -Select the Manage dedicated DB2 instance type 1 - -18.2) Installation Namespace -Install namespace db2u - -18.3) Node Affinity and Tolerations -Note that the same settings are applied to both the IoT and Manage Db2 instances -Use existing node labels and taints to control scheduling of the Db2 workload in your cluster -For more information refer to the Red Hat documentation: - - https://docs.openshift.com/container-platform/4.16/nodes/scheduling/nodes-scheduler-node-affinity.html - - https://docs.openshift.com/container-platform/4.16/nodes/scheduling/nodes-scheduler-taints-tolerations.html -Configure node affinity? [y/n] n -Configure node tolerations? [y/n] n - -18.4) Database CPU & Memory -Note that the same settings are applied to both the IoT and Manage Db2 instances -Customize CPU and memory request/limit? [y/n] n - -18.5) Database Storage Capacity -Note that the same settings are applied to both the IoT and Manage Db2 instances -Customize storage capacity? [y/n] n -``` - -### Configure Grafana -``` -19) Configure Grafana -Install namespace grafana5 -Grafana storage size 10Gi -``` - -### Configure Turbonomic -The [IBM Turbonomic](https://www.ibm.com/products/turbonomic) hybrid cloud cost optimization platform allows you to eliminate this guesswork with solutions that save time and optimize costs. To enable Turbonomic integration you must provide the following information: - -- Target name -- Server URL -- Server version -- Authentication credentials (username & password) - -``` -20) Configure Turbonomic -The IBM Turbonomic hybrid cloud cost optimization platform allows you to eliminate this guesswork with solutions that save time and optimize costs - - Learn more: https://www.ibm.com/products/turbonomic -Configure IBM Turbonomic integration? [y/n] n -``` - -### Additional Configurations -Additional resource definitions can be applied to the OpenShift Cluster during the MAS configuration step, here you will be asked whether you wish to provide any additional configurations and if you do in what directory they reside. - -!!! note - If you provided one or more JDBC configurations in step 9 then additional configurations will already be enabled and be pointing at the directory you chose for the JDBC configurations. - -``` -21) Additional Configuration -Additional resource definitions can be applied to the OpenShift Cluster during the MAS configuration step -The primary purpose of this is to apply configuration for Maximo Application Suite itself, but you can use this to deploy ANY additional resource into your cluster -Use additional configurations? [y/n] n -``` - -### Pod Templates -You can choose between three pre-defined workload scaling classes - `Burstable`, `BestEffort` and `Guaranteed`; or choose a custom profile of your own. By default MAS applications use `Burstable`. - -When choosing a custom profile you will be prompted for the directory of your config files. For each supported application you will need to create separate config file. The naming convention for custom config files is `ibm--.yml`. - -Currently supported config files: - -- ibm-mas - - ibm-mas-bascfg.yml - - ibm-mas-pushnotificationcfg.yml - - ibm-mas-scimcfg.yml - - ibm-mas-slscfg.yml - - ibm-mas-smtpcfg.yml - - ibm-mas-coreidp.yml - - ibm-mas-suite.yml -- ibm-sls - - ibm-sls-licenseservice.yml -- ibm-data-dictionary - - ibm-data-dictionary-assetdatadictionary.yml -- ibm-mas-iot - - ibm-mas-iot-actions.yml - - ibm-mas-iot-auth.yml - - ibm-mas-iot-datapower.yml - - ibm-mas-iot-devops.yml - - ibm-mas-iot-dm.yml - - ibm-mas-iot-dsc.yml - - ibm-mas-iot-edgeconfig.yml - - ibm-mas-iot-fpl.yml - - ibm-mas-iot-guardian.yml - - ibm-mas-iot-iot.yml - - ibm-mas-iot-mbgx.yml - - ibm-mas-iot-mfgx.yml - - ibm-mas-iot-monitor.yml - - ibm-mas-iot-orgmgmt.yml - - ibm-mas-iot-provision.yml - - ibm-mas-iot-registry.yml - - ibm-mas-iot-state.yml - - ibm-mas-iot-webui.yml -- ibm-mas-manage - - ibm-mas-manage-manageapp.yml - - ibm-mas-manage-manageworkspace.yml - - ibm-mas-manage-imagestitching.yml - - ibm-mas-manage-slackproxy.yml - - ibm-mas-manage-healthextworkspace.yml - -For examples on these config files take a look into the pre-defined configs: [BestEffort](https://github.com/ibm-mas/cli/blob/master/image/cli/mascli/templates/pod-templates/best-effort) and [Guaranteed](https://github.com/ibm-mas/cli/blob/master/image/cli/mascli/templates/pod-templates/guaranteed). More information on podTemplates can be found in our official IBM documentation [here](https://www.ibm.com/docs/en/mas-cd/continuous-delivery?topic=configuring-customizing-workloads). - -!!! Note - This feature is only supported starting in MAS 8.11.0 and SLS 3.8.0 - -``` -22) Configure Pod Templates -The CLI supports two pod template profiles out of the box that allow you to reconfigure MAS for either a guaranteed or best effort QoS level -For more information about the Kubernetes quality of service (QoS) levels, see https://kubernetes.io/docs/concepts/workloads/pods/pod-qos/ -You may also choose to use your own customized pod template definitions -Use pod templates? [y/n] n -``` - -### Review Choices -``` -23) Non-Interactive Install Command -Save and re-use the following script to re-run this install without needing to answer the interactive prompts again - -export IBM_ENTITLEMENT_KEY=x -mas install --mas-catalog-version v9-241003-amd64 --ibm-entitlement-key $IBM_ENTITLEMENT_KEY \ - --mas-channel 9.0.x --mas-instance-id mas1 --mas-workspace-id ws1 --mas-workspace-name "ws1" \ - --non-prod \ - --disable-walkme \ - --storage-class-rwo "ibmc-block-gold" --storage-class-rwx "ibmc-file-gold-gid" \ - --storage-pipeline "ibmc-file-gold-gid" --storage-accessmode "ReadWriteMany" \ - --license-file "/mnt/home/entitlement.lic" \ - --uds-email "parkerda@uk.ibm.com" --uds-firstname "David" --uds-lastname "Parker" \ - --dro-namespace "redhat-marketplace" \ - --mongodb-namespace "mongoce" \ - --manage-channel "9.0.x" \ - --manage-jdbc "workspace-application" \ - --manage-components "base=latest" \ - --manage-server-bundle-size "dev" \ - --accept-license --no-confirm - -24) Review Settings -Connected to: - - https://openshift-cluster.containers.appdomain.cloud - -24.1) OpenShift Container Platform - Storage Class Provider .................. ibmc - ReadWriteOnce Storage Class ............. ibmc-block-gold - ReadWriteMany Storage Class ............. ibmc-file-gold-gid - Certificate Manager ..................... redhat - Cluster Ingress Certificate Secret ...... Default - Single Node OpenShift ................... No - Skip Pre-Install Healthcheck ............ No - Skip Grafana-Install .................... No - -24.2) IBM Data Reporter Operator (DRO) Configuration - Contact e-mail .......................... test@uk.ibm.com - First name .............................. David - Last name ............................... Parker - Install Namespace ....................... redhat-marketplace - -24.3) IBM Suite License Service - License File ............................ /mnt/home/entitlement.lic - IBM Open Registry ....................... icr.io/cpopen - -24.4) IBM Maximo Application Suite - Instance ID ............................. mas1 - Workspace ID ............................ ws1 - Workspace Name .......................... ws1 - - Operational Mode ........................ Non-Production - Install Mode ............................ Connected Install - - Manual Certificates ..................... Not Configured - - Enable Guided Tour ...................... false - - Catalog Version ......................... v9-241003-amd64 - Subscription Channel .................... 9.0.x - - IBM Entitled Registry ................... cp.icr.io/cp - IBM Open Registry ....................... icr.io/cpopen - - Trust Default Cert Authorities .......... true - - Additional Config ....................... Not Configured - Pod Templates ........................... Not Configured - -24.5) IBM Maximo Application Suite Applications - IoT ..................................... Do Not Install - Monitor ................................. Do Not Install - Manage .................................. 9.0.x - + Components - + ACM ................................. Disabled - + Aviation ............................ Disabled - + Civil Infrastructure ................ Disabled - + Envizi .............................. Disabled - + Health .............................. Disabled - + HSE ................................. Disabled - + Maximo IT ........................... Disabled - + Nuclear ............................. Disabled - + Oil & Gas ........................... Disabled - + Connector for Oracle ................ Disabled - + Connector for SAP ................... Disabled - + Service Provider .................... Disabled - + Spatial ............................. Disabled - + Strategize .......................... Disabled - + Transportation ...................... Disabled - + Tririga ............................. Disabled - + Utilities ........................... Disabled - + Workday Applications ................ Disabled - + Server bundle size .................... dev - + Enable JMS queues ..................... Default - + Server Timezone ....................... Default - + Base Language ......................... Default - + Additional Languages .................. Default - + Database Settings - + Schema .............................. Default - + Username ............................ Default - + Tablespace .......................... Default - + Indexspace .......................... Default - Loc Srv Esri (arcgis) ................... Do Not Install - Predict ................................. Do Not Install - Optimizer ............................... Do Not Install - Assist .................................. Do Not Install - Visual Inspection ....................... Do Not Install - AI Broker ............................... Do Not Install - -24.6) MongoDb - Install Namespace ....................... mongoce - -24.7) IBM Db2 Univeral Operator Configuration - System Instance ......................... Do Not Install - Dedicated Manage Instance ............... Install - - Type ................................. db2wh - - Timezone ............................. Default - - Install Namespace ....................... db2u - Subscription Channel .................... v110509.0 - - CPU Request ............................. 4000m - CPU Limit ............................... 6000m - Memory Request .......................... 8Gi - Memory Limit ........................... 12Gi - - Meta Storage ............................ 20Gi - Data Storage ............................ 100Gi - Backup Storage .......................... 100Gi - Temp Storage ............................ 100Gi - Transaction Logs Storage ................ 100Gi - - Node Affinity ........................... None - Node Tolerations ........................ None - -24.8) Cloud Object Storage - Type .................................... None - -24.9) Grafana - Install Grafana ......................... Install - -24.10) Turbonomic - Turbonomic Integration .................. Disabled - -Please carefully review your choices above, correcting mistakes now is much easier than after the install has begun -Proceed with these settings? [y/n] y -``` - - -Air Gap Support -------------------------------------------------------------------------------- -If you have already ran `mas configure-airgap` to install the ImageContentSourcePolicy for IBM Maximo Application Suite then the installer will automatically detect the presence of this and tailor the installation configuration for a disconnected installation. - - -More Information -------------------------------------------------------------------------------- -The install is designed to work on any OCP cluster, but has been specifically tested in these environments: - -- IBMCloud ROKS -- Microsoft Azure -- AWS ROSA -- IBM DevIT FYRE (internal) - -### The Automation Engine -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: - -- [Ansible Galaxy: ibm.mas_devops](https://galaxy.ansible.com/ibm/mas_devops) - -### The Automation Driver -The install is performed inside your RedHat OpenShift cluster utilizing [Openshift Pipelines](https://cloud.redhat.com/learn/topics/ci-cd) - -> OpenShift Pipelines is a Kubernetes-native CI/CD solution based on Tekton. It builds on Tekton to provide a CI/CD experience through tight integration with OpenShift and Red Hat developer tools. OpenShift Pipelines is designed to run each step of the CI/CD pipeline in its own container, allowing each step to scale independently to meet the demands of the pipeline. - -![](../img/pipeline.png) - -### Support -The install pipeline supports: - -- IBM Maximo Operator Catalog installation -- Required dependency installation: - - MongoDb (Community Edition) - - IBM Suite License Service - - IBM Data Reporter Operator - - Red Hat Certificate Manager -- Optional dependency installation: - - Apache Kafka - - IBM Db2 - - IBM Cloud Pak for Data Platform and Services - - [Watson Studio](https://www.ibm.com/docs/en/cloud-paks/cp-data/4.0?topic=services-watson-studio) - - [Watson Machine Learning](https://www.ibm.com/docs/en/cloud-paks/cp-data/4.0?topic=services-watson-machine-learning) - - [Watson OpenScale](https://www.ibm.com/docs/en/cloud-paks/cp-data/4.0?topic=services-watson-openscale) - - [Analytics Engine (Apache Spark)](https://www.ibm.com/docs/en/cloud-paks/cp-data/4.0?topic=services-analytics-engine-powered-by-apache-spark) - - Grafana - - Turbonomic Kubernetes Agent -- Suite core services installation -- Suite application installation - -The installer will automatically provision and set up the required dependencies based on the applications that you select to install. - -The install can be launched with the command `mas install`. The end result will be a pipeline run started in your target cluster where you can track the progress of the installation. - -![](../img/pipelineruns.png) diff --git a/docs/commands/mirror-images.md b/docs/commands/mirror-images.md deleted file mode 100644 index 9b138af296c..00000000000 --- a/docs/commands/mirror-images.md +++ /dev/null @@ -1,176 +0,0 @@ -Mirror Images -=============================================================================== - -Usage -------------------------------------------------------------------------------- -`mas mirror-images [options]` - -### Mirror Mode -- `-m|--mode MIRROR_MODE` Operation mode (direct, to-filesystem, from-filesystem) -- `-d|--dir MIRROR_WORKING_DIR` Working directory for the mirror process - -### Registry Details -- `-H|--host REGISTRY_PUBLIC_HOST` Hostname of the target registry -- `-P|--port REGISTRY_PUBLIC_PORT` Port number for the target registry -- `-x|--prefix REGISTRY_PREFIX` Prefix for the mirror image (optional) -- `-u|--username REGISTRY_USERNAME` Username to authenticate to the target registry -- `-p|--password REGISTRY_PASSWORD` Password to authenticate to the target registry - -### Source Registry Entitlement -- `--ibm-entitlement IBM_ENTITLEMENT_KEY` IBM Entitlement Key - -### Maximo Operator Catalog Selection -- `-c|--catalog MAS_CATALOG_VERSION` Maximo Operator Catalog Version to mirror (e.g. @@MAS_LATEST_CATALOG@@) -- `-C|--channel MAS_CHANNEL` Maximo Application Suite Channel to mirror (e.g. @@MAS_LATEST_CHANNEL@@) - -### Content Selection (Core Platform) -- `--mirror-catalog` Mirror the IBM Maximo Operator Catalog -- `--mirror-core` Mirror images for IBM Maximo Application Suite Core - -### Content Selection (Applications) -- `--mirror-assist` Mirror images for IBM Maximo Assist -- `--mirror-hputilities` Mirror images for IBM Maximo Health & Predict Utilities -- `--mirror-iot` Mirror images for IBM Maximo IoT -- `--mirror-manage` Mirror images for IBM Maximo Manage -- `--mirror-icd` Mirror image for IBM Maximo IT (Separately entitled IBM Maximo Manage extension) -- `--mirror-monitor` Mirror images for IBM Maximo Monitor -- `--mirror-optimizer` Mirror images for IBM Maximo Optimizer -- `--mirror-predict` Mirror images for IBM Maximo Predict -- `--mirror-visualinspection` Mirror images for IBM Maximo Visual Inspection - -### Content Selection (Cloud Pak for Data) -- `--mirror-cp4d` Mirror images for IBM Cloud Pak for Data Platform -- `--mirror-wsl` Mirror images for IBM Watson Studio Local -- `--mirror-wml` Mirror images for IBM Watson Machine Learning -- `--mirror-spark` Mirror images for IBM Analytics Engine (Spark) -- `--mirror-cognos` Mirror images for IBM Cognos Analytics - -### Content Selection (Other Dependencies) -- `--mirror-cfs` Mirror images for IBM Cloud Pak Foundation Services -- `--mirror-sls` Mirror images for IBM Suite License Service -- `--mirror-tsm` Mirror images for IBM Truststore Manager -- `--mirror-mongo` Mirror images for MongoDb Community Edition -- `--mirror-db2` Mirror images for IBM Db2 -- `--mirror-appconnect` Mirror images for IBM AppConnect - -### Content Selection (All images included): -- `--mirror-everything` Mirror all MAS related images (including dependencies) - -### Other Options -- `--no-confirm` Mirror images without prompting for confirmation -- `-h|--help` Show help message - - -Storage Requirements -------------------------------------------------------------------------------- -As of MAS 8.10 (June 2023) the total capacity requirement to mirror content from the IBM Maximo Operator Catalog is approximately **484G**, the following table can be used to determine the approximate storage requirement for your mirrored content based on what content you need to mirror: - -| Maximo Application Suite | Command Flag | Size | -| ------------------------------- | --------------------------- | ------- | -| Maximo Operator Catalog | `--mirror-catalog` | 50M | -| Maximo Application Suite Core | `--mirror-core` | 4G | -| Maximo Assist | `--mirror-assist` | 5G | -| Maximo HP Utilities | `--mirror-hputilities` | 2G | -| Maximo IoT | `--mirror-iot` | 9G | -| Maximo Manage | `--mirror-manage` | 8G | -| Maximo Monitor | `--mirror-monitor` | 17G | -| Maximo Optimizer | `--mirror-optimizer` | 3G | -| Maximo Predict | `--mirror-predict` | 6G | -| Maximo Visual Inspection | `--mirror-visualinspection` | 40G | -| **Total** | | **94G** | - -| IBM Cloud Pak for Data | Command Flag | Size | -| ---------------------------- | --------------------------- | -------- | -| IBM CP4D Platform | `--mirror-cp4d` | 2G | -| IBM Analytics Engine (Spark) | `--mirror-spark` | 54G | -| IBM Watson Machine Learning | `--mirror-wml` | 91G | -| IBM Watson Studio Local | `--mirror-wsl` | 85G | -| **Total** | | **273G** | - -| Other Dependencies | Command Flag | Size | -| --------------------------------- | --------------------------- | -------- | -| Mongo Community Edition | `--mirror-mongo` | 500M | -| IBM Truststore Manager | `--mirror-tsm` | 1G | -| IBM Suite License Service | `--mirror-sls` | 1G | -| IBM Cloud Pak Foundation Services | `--mirror-cfs` | 21G | -| IBM AppConnect | `--mirror-appconnect` | 13G | -| IBM Db2 | `--mirror-db2` | 73G | -| **Total** | | **117G** | - -!!! note - The total capacity used on the filesystem in the target mirror registry itself may be lower than this due to the use of shared image layers, particularly across applications in IBM Maximo Application Suite itself. - - -Interactive Image Mirroring -------------------------------------------------------------------------------- -You can start image mirroring by running the `mas mirror-images` command with no parameters, you will be prompted to select the mirror mode and working directory, configure the target registry, and select which content you wish to mirror. - -```bash -docker run -ti --rm -v /mnt/registry:/mnt/registry --pull always quay.io/ibmmas/cli mas mirror-images -``` - - -Direct Image Mirroring -------------------------------------------------------------------------------- -The following example will mirror all images required for Maximo Application Suite Core and the Maximo Manage and IoT applications directly to your target registry, without prompting for confirmation. - -```bash -docker run -ti --rm --pull always quay.io/ibmmas/cli mas mirror-images \ - --mode direct --dir /tmp/registry \ - --ibm-entitlement $IBM_ENTITLEMENT_KEY --redhat-username $REDHAT_USERNAME --redhat-password $REDHAT_PASSWORD \ - -H mirror.mydomain.com -P 5000 -u $MIRROR_USERNAME -p $MIRROR_PASSWORD \ - -c @@MAS_LATEST_CATALOG@@ -C @@MAS_LATEST_CHANNEL@@ \ - --mirror-catalog --mirror-core --mirror-iot --mirror-manage \ - --mirror-cfs --mirror-sls --mirror-tsm --mirror-mongo --mirror-db2 \ - --no-confirm -``` - - -Two-Phase Image Mirroring -------------------------------------------------------------------------------- -Two-Phase image mirroring is required when you do not have a single system with both access to the public registries containing the source container images **and** your internal private registry. In this case you will require a system with internet connectivity and another with access to your private network, along with a means to transfer data from one to the other (for example, a portable drive). - -### Phase 1: Mirror to Filesystem -First, download the latest version of the container image and start up a terminal session inside the container image, we are going to mount a local directory into the running container to persist the mirror filesystem. - -```bash -docker pull quay.io/ibmmas/cli:@@CLI_LATEST_VERSION@@ -docker run -ti --rm -v /registry:/mnt/registry quay.io/ibmmas/cli:@@CLI_LATEST_VERSION@@ mas mirror-images \ - --mode to-filesystem --dir /mnt/registry \ - --ibm-entitlement $IBM_ENTITLEMENT_KEY --redhat-username $REDHAT_USERNAME --redhat-password $REDHAT_PASSWORD \ - -H mirror.mydomain.com -P 5000 -u $MIRROR_USERNAME -p $MIRROR_PASSWORD \ - -c @@MAS_LATEST_CATALOG@@ -C @@MAS_LATEST_CHANNEL@@ \ - --mirror-catalog --mirror-core --mirror-iot --mirror-manage \ - --mirror-cfs --mirror-sls --mirror-tsm --mirror-mongo --mirror-db2 \ - --no-confirm -``` - -Once this process completes you will find the mirrored images in `/registry` on your local filesystem ready to transfer to the system inside your disconnected network on which we will perform phase 2 of this operation. However, before we can do that we also need to mirror the CLI image to your mirror registry so that it's available on the disconnected host system. - -```bash -oc image mirror --dir /registry quay.io/ibmmas/cli:@@CLI_LATEST_VERSION@@ file://ibmmas/cli:@@CLI_LATEST_VERSION@@ -``` - - -### Phase 2: Mirror from Filesystem -Transfer the content of `/registry` to your system in the disconnected network. Now we are going to put the CLI image in your registry: - -```bash -docker login mirror.mydomain.com:5000 -u $MIRROR_USERNAME -p $MIRROR_PASSWORD -oc image mirror --dir /registry file://ibmmas/cli:@@CLI_LATEST_VERSION@@ mirror.mydomain.com:5000/ibmmas/cli:@@CLI_LATEST_VERSION@@ -``` - -Now we are ready to mirror the images to your registry using the CLI image in the same way we mirrored the images to the local disk in the first place: - -```bash -docker pull mirror.mydomain.com:5000/ibmmas/cli:@@CLI_LATEST_VERSION@@ -docker run -ti --rm -v /registry:/mnt/registry mirror.mydomain.com:5000/ibmmas/cli:@@CLI_LATEST_VERSION@@ mas mirror-images \ - --mode from-filesystem --dir /mnt/registry \ - --ibm-entitlement $IBM_ENTITLEMENT_KEY --redhat-username $REDHAT_USERNAME --redhat-password $REDHAT_PASSWORD \ - -H mirror.mydomain.com -P 5000 -u $MIRROR_USERNAME -p $MIRROR_PASSWORD \ - -c @@MAS_LATEST_CATALOG@@ -C @@MAS_LATEST_CHANNEL@@ \ - --mirror-catalog --mirror-core --mirror-iot --mirror-manage \ - --mirror-cfs --mirror-sls --mirror-tsm --mirror-mongo --mirror-db2 \ - --no-confirm -``` - diff --git a/docs/guides/image-mirroring.md b/docs/guides/image-mirroring.md index d9e90d06d52..3c0d6805f56 100644 --- a/docs/guides/image-mirroring.md +++ b/docs/guides/image-mirroring.md @@ -1,16 +1,40 @@ Image Mirroring =============================================================================== +We recommend the use of two-phase mirroring in most cases, it is slower than direct mirroring and requires more storage capacity, but can allow you to more easily recover from network glitches and creates a clean seperation of the tasks of getting the content from the source registry and putting it into the target registry which can make debugging failures easier. +This guide assumes that you are looking to mirror content for the latest release (**@@MAS_LATEST_CHANNEL@@**) from the most recent catalog update (**@@MAS_LATEST_CATALOG@@**), and that you are installing all MAS applications & dependencies. If you are not installing certain applications or dependencies take care to remove the appropriate `--mirror-x` flags to avoid mirroring unnecessary images. + +By default image repositories will be prefixed using the datestamp of the Maximo Operator Catalog that you are mirroring from, this allows for simpler registry management, you can prune all images under `mas-241105/*` in your mirror registry once you know that you have updated all clusters to a newer version of the catalog. -Image Mirroring Overview + +Usage ------------------------------------------------------------------------------- -We recommend the use of two-phase mirroring, it is slower than direct mirroring and requires more storage capacity, but can allow you to more easily recover from network glitches and creates a clean seperation of the tasks of getting the content from the source registry and putting it into the target registry which can make debugging failures easier. +For full usage information run `mas mirror-images --help` -This guide assumes that you are looking to mirror content for the latest release (**@@MAS_LATEST_CHANNEL@@**) from the most recent catalog update (**@@MAS_LATEST_CATALOG@@**), and that you are installing all MAS applications & dependencies. If you are not installing certain applications or dependencies take care to remove the appropriate `--mirror-x` flags to avoid mirroring unnecessary images. +Interactive Image Mirroring +------------------------------------------------------------------------------- +You can start image mirroring by running the `mas mirror-images` command with no parameters, you will be prompted to select the mirror mode and working directory, configure the target registry, and select which content you wish to mirror. + +The easiest way to do this is using the MAS CLI container image as below: + +```bash +LOCAL_DIR=/home/david/mirrorfiles +docker run -ti --rm -v $LOCAL_DIR:/mnt/registry quay.io/ibmmas/cli:@@CLI_LATEST_VERSION@@ mas mirror-images +``` -Preparation + +Non-Interactive Image Mirroring ------------------------------------------------------------------------------- +This guide will take you through we mirror images in our own development environment, breaking up the task into 4 distinct stages to further break down the work and make it easier to address any problems by providing clear milestones: + +- [Preparation](#preparation) +- [IBM Maximo Application Suite Core](#stage-1-core) +- [IBM Maximo Applications](#stage-2-apps) +- [IBM Cloud Pak for Data](#stage-3-cp4d) +- [Other Dependencies](#stage-4-other-dependencies) + +### Preparation Set the following environment variables that will be used in each stage: ```bash @@ -22,78 +46,297 @@ export REGISTRY_USERNAME=xxx export REGISTRY_PASSWORD=xxx ``` +If you do not have a single system with both access to the public source registries **and** your internal private registry then you will require a system with internet connectivity and another with access to your private network, along with a means to transfer data from one to the other (for example, a portable drive). -Stage 1 - Core -------------------------------------------------------------------------------- +In this scenario, we must also transfer the CLI image to your local registry: + +```bash +oc image mirror --dir $LOCAL_DIR/cli quay.io/ibmmas/cli:@@CLI_LATEST_VERSION@@ file://ibmmas/cli:@@CLI_LATEST_VERSION@@ +``` + +Transfer the content of `$LOCAL_DIR/cli` to your system within the private network and transfer the image to your mirror registry. + +```bash +docker login $REGISTRY_HOST:$REGISTRY_PORT -u $REGISTRY_USERNAME -p $REGISTRY_PASSWORD +oc image mirror --dir $LOCAL_DIR/cli file://ibmmas/cli:@@CLI_LATEST_VERSION@@ $REGISTRY_HOST:$REGISTRY_PORT/ibmmas/cli:@@CLI_LATEST_VERSION@@ +``` + + +### Stage 1 - Core Let's start simple and just get the MAS Core and IBM Maximo Operator Catalog mirrored to the registry, this shouldn't take long and provides an early measure of the download and upload performance to help estimate the time to complete the larger stages. + + Direct + To Filesystem + From Filesystem + From Filesystem (Restricted) + + +
+ + + + +
+ + +### Stage 2 - Apps + + + Direct + To Filesystem + From Filesystem + From Filesystem (Restricted) + + +
+ + + + +
+ + +### Stage 3 - CP4D + + + Direct + To Filesystem + From Filesystem + From Filesystem (Restricted) + + +
+ + + + +
+ + +### Stage 4 - Other Dependencies + + + Direct + To Filesystem + From Filesystem + From Filesystem (Restricted) + + +
+ + + + +
+ + +Storage Requirements +------------------------------------------------------------------------------- +As of MAS 8.10 (June 2023) the total capacity requirement to mirror content from the IBM Maximo Operator Catalog is approximately **484G**, the following table can be used to determine the approximate storage requirement for your mirrored content based on what content you need to mirror: + +| Maximo Application Suite | Command Flag | Size | +| ------------------------------- | --------------------------- | ------- | +| Maximo Operator Catalog | `--mirror-catalog` | 50M | +| Maximo Application Suite Core | `--mirror-core` | 4G | +| Maximo Assist | `--mirror-assist` | 5G | +| Maximo IoT | `--mirror-iot` | 9G | +| Maximo Manage | `--mirror-manage` | 8G | +| Maximo Monitor | `--mirror-monitor` | 17G | +| Maximo Optimizer | `--mirror-optimizer` | 3G | +| Maximo Predict | `--mirror-predict` | 6G | +| Maximo Visual Inspection | `--mirror-visualinspection` | 40G | +| **Total** | | **92G** | + +| IBM Cloud Pak for Data | Command Flag | Size | +| ---------------------------- | --------------------------- | -------- | +| IBM CP4D Platform | `--mirror-cp4d` | 2G | +| IBM Analytics Engine (Spark) | `--mirror-spark` | 54G | +| IBM Watson Machine Learning | `--mirror-wml` | 91G | +| IBM Watson Studio Local | `--mirror-wsl` | 85G | +| **Total** | | **273G** | + +| Other Dependencies | Command Flag | Size | +| --------------------------------- | --------------------------- | -------- | +| Mongo Community Edition | `--mirror-mongo` | 500M | +| IBM Truststore Manager | `--mirror-tsm` | 1G | +| IBM Suite License Service | `--mirror-sls` | 1G | +| IBM Cloud Pak Foundation Services | `--mirror-cfs` | 21G | +| IBM AppConnect | `--mirror-appconnect` | 13G | +| IBM Db2 | `--mirror-db2` | 73G | +| **Total** | | **117G** | + +!!! note + The total capacity used on the filesystem in the target mirror registry itself may be lower than this due to the use of shared image layers, particularly across applications in IBM Maximo Application Suite itself. diff --git a/docs/guides/install.md b/docs/guides/install.md index ccc8bc1c307..b120054ae33 100644 --- a/docs/guides/install.md +++ b/docs/guides/install.md @@ -1,26 +1,52 @@ Installation =============================================================================== - -Installation Overview +The install is designed to work on any OCP cluster, but has been specifically tested in these environments: + +- IBMCloud ROKS +- Microsoft Azure +- AWS ROSA +- IBM DevIT FYRE (internal) + +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: + +- IBM Maximo Operator Catalog installation +- Required dependency installation: + - MongoDb (Community Edition) + - IBM Suite License Service + - IBM Data Reporter Operator + - Red Hat Certificate Manager +- Optional dependency installation: + - Apache Kafka + - IBM Db2 + - IBM Cloud Pak for Data Platform and Services + - [Watson Studio Local](https://www.ibm.com/docs/en/cloud-paks/cp-data/4.0?topic=services-watson-studio) + - [Watson Machine Learning](https://www.ibm.com/docs/en/cloud-paks/cp-data/4.0?topic=services-watson-machine-learning) + - [Watson OpenScale](https://www.ibm.com/docs/en/cloud-paks/cp-data/4.0?topic=services-watson-openscale) + - [Analytics Engine (Apache Spark)](https://www.ibm.com/docs/en/cloud-paks/cp-data/4.0?topic=services-analytics-engine-powered-by-apache-spark) + - Cognos Analytics + - Grafana + - Turbonomic Kubernetes Agent +- Suite core services installation +- Suite application installation + +The installation is performed inside your RedHat OpenShift cluster utilizing [Openshift Pipelines](https://cloud.redhat.com/learn/topics/ci-cd) + +> OpenShift Pipelines is a Kubernetes-native CI/CD solution based on Tekton. It builds on Tekton to provide a CI/CD experience through tight integration with OpenShift and Red Hat developer tools. OpenShift Pipelines is designed to run each step of the CI/CD pipeline in its own container, allowing each step to scale independently to meet the demands of the pipeline. + +![](../img/pipeline.png) + + +Usage ------------------------------------------------------------------------------- -1. [Pre-requistes](#1-pre-requisites) - - 1.1 [IBM Entitlement Key](#11-ibm-entitlement-key) - - 1.2 [MAS License File](#12-mas-license-file) - - 1.3 [OpenShift Cluster](#13-openshift-cluster) - - 1.4 [Operator Catalog Selection](#14-operator-catalog-selection) -2. [Disconnected Install Preparation](#2-disconnected-install-preparation) - - 2.1 [Prepare your Private Registry](#21-prepare-the-private-registry) - - 2.2 [Mirror Container Images](#22-mirror-container-images) - - 2.3 [Configure OpenShift to use your Private Registry for MAS](#23-configure-openshift-to-use-your-private-registry-for-mas) -3. [Install MAS](#3-install-maximo-application-suite) - - -1 Pre-requisites +For full usage information run `mas install --help` + + +Preparation ------------------------------------------------------------------------------- -### 1.1 IBM Entitlement Key +### IBM Entitlement Key Access [Container Software Library](https://myibm.ibm.com/products-services/containerlibrary) using your IBMId to obtain your entitlement key. -### 1.2 MAS License File +### MAS License File Access [IBM License Key Center](https://licensing.flexnetoperations.com/), on the **Get Keys** menu select **IBM AppPoint Suites**. Select `IBM MAXIMO APPLICATION SUITE AppPOINT LIC` and on the next page fill in the information as below: | Field | Content | @@ -37,7 +63,7 @@ The other values can be left at their defaults. Finally, click **Generate** and !!! note For more information about how to access the IBM License Key Center review the [getting started documentation](https://www.ibm.com/support/pages/system/files/inline-files/GettingStartedEnglish_2020.pdf) available from the IBM support website. -### 1.3 OpenShift Cluster +### OpenShift Cluster 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.openshift.com/container-platform/4.15/installing/index.html). The CLI also supports OpenShift provisioning in many hyperscaler providers: @@ -47,13 +73,13 @@ The CLI also supports OpenShift provisioning in many hyperscaler providers: - [IBM DevIT FYRE (Internal)](../commands/provision-fyre.md) -### 1.4 Operator Catalog Selection +### 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. -2 Disconnected Install Preparation +Disconnected Install Preparation ------------------------------------------------------------------------------- -### 2.1 Prepare the Private Registry +### Prepare the Private Registry You must have a production grade Docker v2 compatible registry such as [Quay Enterprise](https://www.redhat.com/en/technologies/cloud-computing/quay), [JFrog Artifactory](https://jfrog.com/integration/docker-registry/), or [Docker Registry](https://docs.docker.com/registry/). If you do not already have a private registry available to use as your mirror then you can use the `setup-mirror` function to deploy a private registry using the [Docker registry container image](https://hub.docker.com/_/registry) inside a target OpenShift cluster. ```bash @@ -73,34 +99,17 @@ The registry will be setup running on port 32500. For more details on this step | Password | Optional. Authentication password for the registry. | -### 2.2 Mirror Container Images +### Mirror Container Images Mirroring the images is a simple but time consuming process, this step must be performed from a system with internet connectivity and network access your private registry, but does not need access to your target OpenShift cluster. Three modes are available for the mirror process: - **direct** mirrors images directly from the source registry to your private registry - **to-filesystem** mirrors images from the source to a local directory - **from-filesystem** mirrors images from a local directory to your private registry -```bash -docker run -ti --pull always quay.io/ibmmas/cli mas mirror-images -``` - -You will be prompted to set the target registry for the image mirroring, to select the version of IBM Maximo Operator Catalog to mirror, and the subset of content that you wish to mirror. You can choose to mirror everything from the catalog, or control exactly what is mirrored to your private registry to reduce the time and bandwidth used to mirror the images, as well reducing the storage requirements of the registry. - -The following command will mirror all required and optional content that makes up the IBM Maximo Operator Catalog directly to your mirror registry, for full usgae information refer to the [mirror-images](../commands/mirror-images.md) command documentation, if you are looking for more detailed guidance on how to approach this activity refer to the [image mirroring guide](image-mirroring.md). +For full details on this process review the [image mirroring](image-mirroring.md) guide. -```bash -mas mirror-images -m direct -d /mnt/local-mirror \ - -H myprivateregistry.com -P 5000 -u $REGISTRY_USERNAME -p $REGISTRY_PASSWORD \ - -c @@MAS_LATEST_CATALOG@@ -C @@MAS_LATEST_CHANNEL@@ \ - --mirror-catalog --mirror-core \ - --mirror-assist --mirror-iot --mirror-manage --mirror-icd --mirror-monitor --mirror-optimizer --mirror-predict --mirror-visualinspection \ - --mirror-cp4d --mirror-spark --mirror-wml --mirror-wsl --mirror-cognos \ - --mirror-mongo --mirror-tsm --mirror-sls --mirror-cfs --mirror-db2 --mirror-appconnect \ - --ibm-entitlement $IBM_ENTITLEMENT_KEY \ - --no-confirm -``` -### 2.3 Configure OpenShift to use your Private Registry for MAS +### 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. ```bash @@ -119,12 +128,137 @@ mas configure-airgap \ ``` -3 Install Maximo Application Suite +Interactive Install ------------------------------------------------------------------------------- -Regardless of whether you are running a connected or disconnect installation, simply run the `mas install` command and follow the prompts. +Regardless of whether you are running a connected or disconnected installation, simply run the `mas install` command and follow the prompts, the basic structure of the interactive flow is described below. ```bash -docker run -ti --pull always quay.io/ibmmas/cli mas install +docker run -ti --rm -v ~:/mnt/home quay.io/ibmmas/cli:@@CLI_LATEST_VERSION@@ mas install ``` -Refer to the [Interactive Install](../commands/install.md#interactive-install) section in the install command reference for more information. +!!! important + We will need the `entitlement.lic` file to perform the installation which is why we mount your home directory into the container. If you saved the entitlement file elsewhere, mount that directory instead. + + When prompted you will be able to set license file to `/mnt/home/entitlement.lic` + + +### Connect to OpenShift and Choose a Catalog +- If you are not already connected to an OpenShift cluster you will be prompted to provide the server URL & token to make a new connection. If you are already connected to a cluster you will be given the option to change to another cluster +- You will be presented with a table of available catalogs with information about the different releases of MAS available in each +- Confirm that you accept the IBM Maximo Application Suite license terms + + +### Select Storage Classes +MAS requires both a `ReadWriteMany` and a `ReadWriteOnce` capable storage class to be available in the cluster. The installer has the ability to recognize certain storage class providers and will default to the most appropriate storage class in these cases: + +- IBMCloud Storage (`ibmc-block-gold` & `ibmc-file-gold-gid`) +- OpenShift Container Storage (`ocs-storagecluster-ceph-rbd` & `ocs-storagecluster-cephfs`) +- External OpenShift Container Storage (`ocs-external-storagecluster-ceph-rbd` & `ocs-external-storagecluster-cephfs`) +- NFS Client (`nfs-client`) +- Azure Managed Storage (`managed-premium` & `azurefiles-premium`) +- AWS Storage (`gp3-cs` & `efs`) + +The names in brackets represent the `ReadWriteOnce` and `ReadWriteMany` class that will be used, in the case of NFS the same storage class will be used for both `ReadWriteOnce` and `ReadWriteMany` volumes. Even when a recognized storage provider is detected you will be provided with the option to select your own storages classes if you wish. + +When selecting your own storage classes you will be presented with a list of those available and must select both a `ReadWriteMany` and a `ReadWriteOnce` storage class. + +!!! warning + Unfortunately there is no way for the install to verify that the storage class selected actually supports the appropriate access mode, refer to the documentation from the storage class provider to determine whether your storage class supports `ReadWriteOnce` and/or `ReadWriteMany`. + + +### Provide a License File and Entitlement Key +Provide the location of your license file, contact information, and IBM entitlement key (if you have set the `IBM_ENTITLEMENT_KEY` environment variable then this field will be pre-filled with that value already). + + +### Configure your MAS Instance +Provide the basic information about your MAS instance: + +- Instance ID +- Workspace ID +- Workspace Display Name +- Operational Mode (production or non-production) + + +### Configure Domain & Certificate Management +By default MAS will be installed in a subdomain of your OpenShift clusters domain matching the MAS instance ID that you chose. For example if your OpenShift cluster is `myocp.net` and you are installing MAS with an instance ID of `prod1` then MAS will be installed with a default domain something like `prod1.apps.myocp.net`, depending on the exact network configuration of your cluster. + +If you wish to use a custom domain for the MAS install you can choose to configure this by selecting "n" at the prompt. The install supports DNS integrations for Cloudflare, IBM Cloud Internet Services, AWS Route 53 out of the box and is able to configure a certificate issuer using LetsEncrypt (production or staging) or a self-signed certificate authority per your choices. + + +### Advanced Settings +You will also be able to configure the following advanced settings: + +- Single Sign-On (SSO) +- Whether to allow special character in User IDs and Usernames +- Whether Guided Tours are enabled + + +### Application Selection +Select the applications that you would like to install. Note that some applications cannot be installed unless an application they depend on is also installed: + +- Monitor is only available for install if IoT is selected +- Assist and Predict are only available for install if Monitor is selected + + +### Application Configuration +Some Maximo applications support additional configuration, you will be taken through the configuration options for each application that you chose to install + + +### Configure Databases +The install supports the automatic provision of in-cluster MongoDb and Db2 databases for use with Maximo Application Suite, you may also choose to bring your own (BYO) by providing the necessary configuration files (which the installer will also help you create). + + +### Configure Integrations & Additional Configuration +The install supports the abilty to install and configure Turbonomic's Kubeturbo operator and the Grafana Community Operator. Additional resource definitions can be applied to the OpenShift Cluster during the MAS configuration step, here you will be asked whether you wish to provide any additional configurations and if you do in what directory they reside. + +!!! note + If you provided one or more configurations for BYO databases then additional configurations will already be enabled and pointing at the directory you chose earlier. + + +### Pod Templates +You can choose between three pre-defined pod templates allowing you to configure MAS in each of the standard Kubernetes quality of service (QoS) levels: **Burstable**, [**BestEffort**](https://github.com/ibm-mas/cli/blob/master/image/cli/mascli/templates/pod-templates/best-effort) and [**Guaranteed**](https://github.com/ibm-mas/cli/blob/master/image/cli/mascli/templates/pod-templates/guaranteed). By default MAS applications are deployed with a `Burstable` QoS. + +Additionally, you may provide your own custom pod templates definition by providing the directory containing your configuration files. More information on podTemplates can be found in the [product documentation](https://www.ibm.com/docs/en/mas-cd/continuous-delivery?topic=configuring-customizing-workloads). + +!!! Note + Pod templating support is only available in IBM Maximo Application Suite v8.11+ + + +### Review Choices +Before the install actually starts you will be presented with a summary of all your choices and a non-interactive command that will allow you to repeat the same installation without going through all the prompts again. + + +Non-Interactive Install +------------------------------------------------------------------------------- +The following command will launch the MAS CLI container image, login to your OpenShift Cluster and start the install of MAS without triggering any prompts. This is how we install MAS in development hundreds of times every single week. + +```bash +IBM_ENTITLEMENT_KEY=xxx +SUPERUSER_PASSWORD=xxx + +docker run -e IBM_ENTITLEMENT_KEY -e SUPERUSER_PASSWORD -ti --rm -v ~:/mnt/home quay.io/ibmmas/cli:@@CLI_LATEST_VERSION@@ bash -c " + oc login --token=sha256~xxxx --server=https://xxx && + mas install \ + --mas-catalog-version @@MAS_LATEST_CATALOG@@ \ + --mas-instance-id mas1 \ + --mas-workspace-id ws1 \ + --mas-workspace-name "My Workspace" + \ + --superuser-username superuser \ + --superuser-password '${SUPERUSER_PASSWORD}' \ + \ + --mas-channel @@MAS_LATEST_CHANNEL@@ \ + \ + --ibm-entitlement-key '${IBM_ENTITLEMENT_KEY}' \ + --license-file /mnt/home/entitlement.lic \ + --uds-email myemail@email.com \ + --uds-firstname John \ + --uds-lastname Barnes \ + \ + --storage-rwo ibmc-block-gold \ + --storage-rwx ibmc-file-gold-gid \ + --storage-pipeline ibmc-file-gold-gid \ + --storage-accessmode ReadWriteMany \ + \ + --accept-license --no-confirm +``` diff --git a/docs/guides/update.md b/docs/guides/update.md index a4bbb79aea6..b34b25702e9 100644 --- a/docs/guides/update.md +++ b/docs/guides/update.md @@ -29,7 +29,7 @@ docker run -ti --rm --pull always quay.io/ibmmas/cli mas mirror-images You will be prompted to set the target registry for the image mirroring, to select the version of IBM Maximo Operator Catalog to mirror, and the subset of content that you wish to mirror. You can choose to mirror everything from the catalog, or control exactly what is mirrored to your private registry to reduce the time and bandwidth used to mirror the images, as well reducing the storage requirements of the registry. -This command can also be ran non-interactive, for full details refer to the [mirror-images](../commands/mirror-images.md) command documentation. +This command can also be ran non-interactive, for full details refer to the [image mirroring](../guides/image-mirroring.md) guide. ```bash mas mirror-images -m direct -d /mnt/local-mirror \ diff --git a/docs/guides/upgrade.md b/docs/guides/upgrade.md index 1aee57e9efa..603b440644e 100644 --- a/docs/guides/upgrade.md +++ b/docs/guides/upgrade.md @@ -34,7 +34,7 @@ docker run -ti --rm --pull always quay.io/ibmmas/cli mas mirror-images You will be prompted to set the target registry for the image mirroring and to [select the version of IBM Maximo Operator Catalog to mirror](../catalogs/index.md) and the subset of content that you wish to mirror. You can choose to mirror everything from the catalog, or control exactly what is mirrored to your private registry to reduce the time and bandwidth used to mirror the images, as well reducing the storage requirements of the registry. -This command can also be ran non-interactive, for full details refer to the [mirror-images](../commands/mirror-images.md) command documentation. +This command can also be ran non-interactive, for full details refer to the [image mirroring](../guides/image-mirroring.md) guide. ```bash mas mirror-images -m direct -d /mnt/local-mirror \ diff --git a/docs/index.md b/docs/index.md index 0314a72e123..cb0f5982e42 100644 --- a/docs/index.md +++ b/docs/index.md @@ -46,13 +46,13 @@ Not all functions supported in the container image are available in the standalo | CLI Function | Image | Binary | | -------------------------------------------------------- | :------: | :------: | -| [install](commands/install.md) | ✓ | ✓ | +| [install](guides/install.md) | ✓ | ✓ | | [update](commands/update.md) | ✓ | ✓ | | [upgrade](commands/upgrade.md) | ✓ | ✓ | | [uninstall](commands/uninstall.md) | ✓ | ✓ | | [must-gather](commands/must-gather.md) | ✓ | ✕ | | [configure-airgap](commands/configure-airgap.md) | ✓ | ✕ | -| [mirror-images](commands/mirror-images.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) | ✓ | ✕ | diff --git a/image/cli/Dockerfile b/image/cli/Dockerfile index b10bb018858..a1e43c1f1f6 100644 --- a/image/cli/Dockerfile +++ b/image/cli/Dockerfile @@ -16,7 +16,8 @@ ENV ANSIBLE_COLLECTIONS_PATH=/opt/app-root/lib64/python3.9/site-packages/ansible ANSIBLE_CONFIG=/opt/app-root/src/ansible.cfg \ PATH="/mascli:${PATH}" \ VERSION=${VERSION_LABEL:-x.y.z} \ - VIRTUAL_ENV_DISABLE_PROMPT=1 + VIRTUAL_ENV_DISABLE_PROMPT=1 \ + PYTHONWARNINGS="ignore:Unverified HTTPS request" # 3. Install Python packages # 4. Install Ansible collections diff --git a/image/cli/mascli/functions/configure_airgap b/image/cli/mascli/functions/configure_airgap index 82254e3eee2..a7deea4688a 100644 --- a/image/cli/mascli/functions/configure_airgap +++ b/image/cli/mascli/functions/configure_airgap @@ -83,7 +83,6 @@ function configure_ocp_for_mirror_noninteractive() { # Check all args have been set [[ -z "$REGISTRY_PRIVATE_HOST" ]] && configure_ocp_for_mirror_help "REGISTRY_PRIVATE_HOST is not set" - [[ -z "$REGISTRY_PRIVATE_PORT" ]] && configure_ocp_for_mirror_help "REGISTRY_PRIVATE_PORT is not set" [[ -z "$REGISTRY_PRIVATE_CA_FILE" ]] && configure_ocp_for_mirror_help "REGISTRY_PRIVATE_CA_FILE is not set" [[ -z "$REGISTRY_USERNAME" ]] && configure_ocp_for_mirror_help "REGISTRY_USERNAME is not set" [[ -z "$REGISTRY_PASSWORD" ]] && configure_ocp_for_mirror_help "REGISTRY_PASSWORD is not set" @@ -111,6 +110,14 @@ function configure_ocp_for_mirror_interactive() { exit 1 fi + if [[ "$REGISTRY_PRIVATE_PORT" != "" ]]; then + REGISTRY_PRIVATE_URL = "${REGISTRY_PRIVATE_HOST}:${REGISTRY_PRIVATE_PORT}" + fi + + if [[ "$REGISTRY_PREFIX" != "" ]]; then + REGISTRY_PRIVATE_URL_WITH_PATH = "${REGISTRY_PRIVATE_URL}/${REGISTRY_PREFIX}" + fi + echo echo_h2 "Configure Authentication" prompt_for_input "Mirror Registry Username" REGISTRY_USERNAME && export REGISTRY_USERNAME @@ -123,9 +130,9 @@ function configure_ocp_for_mirror_interactive() { echo echo "1. OperatorHub will be re-configured to disable the default online catalog sources" echo "2. Three offline catalog sources will be created/updated in the openshift-marketplace namespace:" - echo " - certified-operator-index -> $REGISTRY_PRIVATE_HOST:$REGISTRY_PRIVATE_PORT/redhat/certified-operator-index:v$OCP_RELEASE" - echo " - community-operator-index -> $REGISTRY_PRIVATE_HOST:$REGISTRY_PRIVATE_PORT/redhat/community-operator-index:v$OCP_RELEASE" - echo " - redhat-operator-index -> $REGISTRY_PRIVATE_HOST:$REGISTRY_PRIVATE_PORT/redhat/redhat-operator-index:v$OCP_RELEASE" + echo " - certified-operator-index -> $REGISTRY_PRIVATE_URL_WITH_PATH/redhat/certified-operator-index:v$OCP_RELEASE" + echo " - community-operator-index -> $REGISTRY_PRIVATE_URL_WITH_PATH/redhat/community-operator-index:v$OCP_RELEASE" + echo " - redhat-operator-index -> $REGISTRY_PRIVATE_URL_WITH_PATH/redhat/redhat-operator-index:v$OCP_RELEASE" echo reset_colors @@ -185,12 +192,11 @@ function configure_ocp_for_mirror() { echo_h2 "Disable Online Red Hat Catalog Sources" ROLE_NAME=ocp_config ansible-playbook ibm.mas_devops.run_role || exit 1 - echo_h2 "Configure Image Content Source Policy (with Red Hat catalogs)" - ROLE_NAME=ocp_contentsourcepolicy ansible-playbook ibm.mas_devops.run_role || exit 1 + echo_h2 "Configure ImageDigestMirrorSet (with Red Hat catalogs)" + ROLE_NAME=ocp_idms ansible-playbook ibm.mas_devops.run_role || exit 1 else - echo_h2 "Configure Image Content Source Policy" - ROLE_NAME=ocp_contentsourcepolicy ansible-playbook ibm.mas_devops.run_role || exit 1 + echo_h2 "Configure ImageDigestMirrorSet" + ROLE_NAME=ocp_idms ansible-playbook ibm.mas_devops.run_role || exit 1 fi - } diff --git a/image/cli/mascli/functions/mirror_images b/image/cli/mascli/functions/mirror_images index bc9ba354398..74aef518b81 100644 --- a/image/cli/mascli/functions/mirror_images +++ b/image/cli/mascli/functions/mirror_images @@ -307,20 +307,34 @@ function mirror_to_registry_noninteractive() { [[ -z "$IBM_ENTITLEMENT_KEY" ]] && mirror_to_registry_help "IBM_ENTITLEMENT_KEY is not set" [[ -z "$REGISTRY_PUBLIC_HOST" ]] && mirror_to_registry_help "REGISTRY_PUBLIC_HOST is not set" - [[ -z "$REGISTRY_PUBLIC_PORT" ]] && mirror_to_registry_help "REGISTRY_PUBLIC_PORT is not set" if [[ $MIRROR_MODE != "to-filesystem" ]]; then [[ -z "$REGISTRY_USERNAME" ]] && mirror_to_registry_help "REGISTRY_USERNAME is not set" [[ -z "$REGISTRY_PASSWORD" ]] && mirror_to_registry_help "REGISTRY_PASSWORD is not set" fi + # Provide a default prefix - For future consideration + # if [[ "$REGISTRY_PREFIX" == "" ]]; then + # REGISTRY_PREFIX=${MAS_CATALOG_VERSION#*-} # removes the "v9-" prefix + # REGISTRY_PREFIX="mas-${REGISTRY_PREFIX%%-*}" # removes the -arch suffix + # fi + if [[ "$MIRROR_EVERYTHING" == "true" ]]; then - mirror_everything + mirror_everything fi } function mirror_to_registry_interactive() { load_config + echo + echo_h2 "Configure Catalog Version (see https://ibm-mas.github.io/cli/catalogs/ for details on catalogs)" + prompt_for_input "MAS Catalog Version" MAS_CATALOG_VERSION + prompt_for_input "MAS Channel" MAS_CHANNEL + + # Provide a default prefix - For future consideration + # DEFAULT_REGISTRY_PREFIX=${MAS_CATALOG_VERSION#*-} # removes the "v9-" prefix + # DEFAULT_REGISTRY_PREFIX="mas-${DEFAULT_REGISTRY_PREFIX%%-*}" # removes the -arch suffix + echo echo_h2 "Configure Mirror Mode" prompt_for_input "Working Directory" MIRROR_WORKING_DIR @@ -360,18 +374,13 @@ function mirror_to_registry_interactive() { prompt_for_secret "Mirror Registry Password" REGISTRY_PASSWORD "Re-use saved registry password?" fi - echo - echo_h2 "Configure Static Catalog Version (see https://ibm-mas.github.io/cli/catalogs/ for details on catalogs)" - prompt_for_input "MAS Catalog Version" MAS_CATALOG_VERSION - prompt_for_input "MAS Channel" MAS_CHANNEL - echo echo_h2 "Configure Images to Mirror" prompt_for_confirm "Mirror all MAS images (with dependencies)" MIRROR_EVERYTHING if [[ "$MIRROR_EVERYTHING" == "true" ]]; then - mirror_everything + mirror_everything else prompt_for_confirm_default_yes "IBM Maximo Operator Catalog" MIRROR_CATALOG @@ -436,7 +445,7 @@ function mirror_to_registry_interactive() { prompt_for_confirm "IBM Cognos Analytics" MIRROR_COGNOS prompt_for_confirm "IBM AppConnect" MIRROR_APPCONNECT - prompt_for_confirm "RedHat ODF" MIRROR_ODF + prompt_for_confirm "Red Hat ODF" MIRROR_ODF fi if [[ "$MIRROR_MAS_ICD" == "true" ]]; then @@ -563,18 +572,19 @@ function mirror_to_registry() { reset_colors echo_h2 "Review Settings" + REGISTRY_URL=$REGISTRY_PUBLIC_HOST + if [[ "$REGISTRY_PUBLIC_PORT" != "" ]]; then + REGISTRY_URL+=":$REGISTRY_PUBLIC_PORT" + fi + if [[ "$REGISTRY_PREFIX" != "" ]]; then + REGISTRY_URL+="/$REGISTRY_PREFIX" + fi + echo echo_h4 "Settings" " " echo_reset_dim "Mirror Mode ......................... ${COLOR_MAGENTA}${MIRROR_MODE}" echo_reset_dim "Working Directory ................... ${COLOR_MAGENTA}${MIRROR_WORKING_DIR}" - - echo - reset_colors - echo_h4 "Target Registry" " " - echo_reset_dim "Registry Host ....................... ${COLOR_MAGENTA}${REGISTRY_PUBLIC_HOST}" - echo_reset_dim "Registry Port ....................... ${COLOR_MAGENTA}${REGISTRY_PUBLIC_PORT}" - echo_reset_dim "Registry Prefix ..................... ${COLOR_MAGENTA}${REGISTRY_PREFIX}" - + echo_reset_dim "Target Registry ..................... ${COLOR_MAGENTA}${REGISTRY_URL}" echo reset_colors diff --git a/image/cli/mascli/functions/mirror_redhat b/image/cli/mascli/functions/mirror_redhat index 2dfcc669a84..4068054defd 100644 --- a/image/cli/mascli/functions/mirror_redhat +++ b/image/cli/mascli/functions/mirror_redhat @@ -35,7 +35,7 @@ function mirror_redhat_noninteractive() { REGISTRY_PUBLIC_PORT=$1 && shift ;; -x| --prefix) - REGISTRY_PREFIX=$1 && shift + REGISTRY_PREFIX_REDHAT=$1 && shift ;; -u|--username) REGISTRY_USERNAME=$1 && shift @@ -84,7 +84,6 @@ function mirror_redhat_noninteractive() { if [[ "$MIRROR_MODE" == "direct" ]] || [[ "$MIRROR_MODE" == "from-filesystem" ]]; then [[ -z "$REGISTRY_PUBLIC_HOST" ]] && mirror_redhat_help "REGISTRY_PUBLIC_HOST is not set" - [[ -z "$REGISTRY_PUBLIC_PORT" ]] && mirror_redhat_help "REGISTRY_PUBLIC_PORT is not set" fi [[ -z "$REDHAT_PULLSECRET" ]] && mirror_redhat_help "REDHAT_PULLSECRET is not set" @@ -96,6 +95,11 @@ function mirror_redhat_noninteractive() { exit 0 fi fi + + # Provide a default prefix - For future consideration + # if [[ "$REGISTRY_PREFIX_REDHAT" == "" ]]; then + # REGISTRY_PREFIX_REDHAT="ocp-${OCP_RELEASE/./}" + # fi } function mirror_redhat_interactive() { @@ -125,23 +129,6 @@ function mirror_redhat_interactive() { ;; esac - if [[ "$MIRROR_MODE" == "direct" ]] || [[ "$MIRROR_MODE" == "from-filesystem" ]]; then - echo - echo_h2 "Configure Target Mirror" - prompt_for_input "Mirror Registry Host" REGISTRY_PUBLIC_HOST - prompt_for_input "Mirror Registry Port" REGISTRY_PUBLIC_PORT - prompt_for_input "Mirror Registry Prefix" REGISTRY_PREFIX - prompt_for_input "Mirror Registry Username" REGISTRY_USERNAME - prompt_for_secret "Mirror Registry Password" REGISTRY_PASSWORD "Re-use saved registry password?" - fi - - echo - echo_h2 "Configure Red Hat Authentication" - echo "Path to your Red Hat pull secret, available from:" - echo " - ${COLOR_CYAN}${TEXT_UNDERLINE}https://console.redhat.com/openshift/install/pull-secret${TEXT_RESET}" - echo - prompt_for_input "Red Hat Pull Secret" REDHAT_PULLSECRET - echo echo_h2 "Configure Images to Mirror" echo_h3 "Select OCP Release" @@ -172,16 +159,45 @@ function mirror_redhat_interactive() { ;; esac + # Provide a default prefix - For future consideration + # DEFAULT_REGISTRY_PREFIX_REDHAT="ocp-${OCP_RELEASE/./}" + + if [[ "$MIRROR_MODE" == "direct" ]] || [[ "$MIRROR_MODE" == "from-filesystem" ]]; then + echo + echo_h2 "Configure Target Mirror" + prompt_for_input "Mirror Registry Host" REGISTRY_PUBLIC_HOST + prompt_for_input "Mirror Registry Port" REGISTRY_PUBLIC_PORT + prompt_for_input "Mirror Registry Prefix" REGISTRY_PREFIX_REDHAT + prompt_for_input "Mirror Registry Username" REGISTRY_USERNAME + prompt_for_secret "Mirror Registry Password" REGISTRY_PASSWORD "Re-use saved registry password?" + fi + + REGISTRY_URL=$REGISTRY_PUBLIC_HOST + if [[ "$REGISTRY_PUBLIC_PORT" != "" ]]; then + REGISTRY_URL+=":$REGISTRY_PUBLIC_PORT" + fi + if [[ "$REGISTRY_PREFIX_REDHAT" != "" ]]; then + REGISTRY_URL+="/$REGISTRY_PREFIX_REDHAT" + fi + + echo + echo_h2 "Configure Red Hat Authentication" + echo "Path to your Red Hat pull secret, available from:" + echo " - ${COLOR_CYAN}${TEXT_UNDERLINE}https://console.redhat.com/openshift/install/pull-secret${TEXT_RESET}" + echo + prompt_for_input "Red Hat Pull Secret" REDHAT_PULLSECRET + + echo_h3 "Red Hat OCP Release" echo "${TEXT_DIM}Mirror the Red Hat OCP release to your registry, you must select the mininum and maximum version of the release that you want mirrored." echo if [[ "$MIRROR_MODE" == "direct" ]] || [[ "$MIRROR_MODE" == "from-filesystem" ]]; then echo "Images will be mirrored to:" - echo " - $REGISTRY_PUBLIC_HOST:$REGISTRY_PUBLIC_PORT/openshift/release" - echo " - $REGISTRY_PUBLIC_HOST:$REGISTRY_PUBLIC_PORT/openshift/release-images" + echo " - $REGISTRY_URL/openshift/release" + echo " - $REGISTRY_URL/openshift/release-images" echo fi - echo "An ImageContentSourcePolicy must be configured in the cluster to make use of the mirrored release (see ${COLOR_CYAN}mas configure-airgap${TEXT_RESET})" + echo "An ImageDigestMirrorSet must be configured in the cluster to make use of the mirrored release (see ${COLOR_CYAN}mas configure-airgap${TEXT_RESET})" echo prompt_for_confirm "Mirror Red Hat OCP release" MIRROR_REDHAT_PLATFORM @@ -211,7 +227,7 @@ function mirror_redhat_interactive() { echo " - local-storage-operator (stable)" echo " - odf-operator (stable-${OCP_RELEASE})" echo - echo "An ImageContentSourcePolicy must be configured in the cluster to make use of the mirrored release (see ${COLOR_CYAN}mas configure-airgap${TEXT_RESET})" + echo "An ImageDigestMirrorSet must be configured in the cluster to make use of the mirrored release (see ${COLOR_CYAN}mas configure-airgap${TEXT_RESET})" echo prompt_for_confirm "Mirror selected content from Red Hat OCP operator catalogs" MIRROR_REDHAT_OPERATORS @@ -241,7 +257,7 @@ function mirror_redhat() { # Target Registry export REGISTRY_PUBLIC_HOST export REGISTRY_PUBLIC_PORT - export REGISTRY_PREFIX + export REGISTRY_PREFIX_REDHAT export REGISTRY_USERNAME export REGISTRY_PASSWORD @@ -255,13 +271,7 @@ function mirror_redhat() { echo_reset_dim "Authentication ........................ ${COLOR_MAGENTA}${REDHAT_PULLSECRET}" if [[ "$MIRROR_MODE" == "direct" ]] || [[ "$MIRROR_MODE" == "from-filesystem" ]]; then - echo - reset_colors - echo_h4 "Target Registry" " " - echo_reset_dim "Registry Host ......................... ${COLOR_MAGENTA}${REGISTRY_PUBLIC_HOST}" - echo_reset_dim "Registry Port ......................... ${COLOR_MAGENTA}${REGISTRY_PUBLIC_PORT}" - echo_reset_dim "Registry Prefix ....................... ${COLOR_MAGENTA}${REGISTRY_PREFIX}" - reset_colors + echo_reset_dim "Target Registry ....................... ${COLOR_MAGENTA}${REGISTRY_URL}" fi echo diff --git a/mkdocs.yml b/mkdocs.yml index 39ddf24c75d..e4cab1f2fbf 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -18,13 +18,11 @@ nav: - "EAM Migration": examples/eam-migration.md - "Mirror Db2 Images": examples/mirror-db2.md - "Command Reference": - - "install": commands/install.md - "update": commands/update.md - "upgrade": commands/upgrade.md - "uninstall": commands/uninstall.md - "must-gather": commands/must-gather.md - "configure-airgap": commands/configure-airgap.md - - "mirror-images": commands/mirror-images.md - "mirror-redhat-images": commands/mirror-redhat-images.md - "setup-registry": commands/setup-registry.md - "teardown-registry": commands/teardown-registry.md @@ -80,6 +78,8 @@ plugins: "guides/architecture/core.md": "https://www.ibm.com/docs/en/mas-cd/continuous-delivery?topic=reference-maximo-application-suite-core-services" "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" - glightbox: shadow: true caption_position: bottom diff --git a/python/setup.py b/python/setup.py index 1fc6dfbda0c..71566ed2701 100644 --- a/python/setup.py +++ b/python/setup.py @@ -58,7 +58,7 @@ def get_version(rel_path): description='Python Admin CLI for Maximo Application Suite', long_description=long_description, install_requires=[ - 'mas-devops >= 1.10.0', # EPL + 'mas-devops >= 2.0.0', # EPL 'halo', # MIT License 'prompt_toolkit', # BSD License 'openshift', # Apache Software License diff --git a/python/src/mas/cli/cli.py b/python/src/mas/cli/cli.py index 084b6fc942e..533095ce1fa 100644 --- a/python/src/mas/cli/cli.py +++ b/python/src/mas/cli/cli.py @@ -138,6 +138,7 @@ def __init__(self): self.certsSecret = None self._isSNO = None + self._isAirgap = None # Until we connect to the cluster we don't know what architecture it's worker nodes are self.architecture = None @@ -280,6 +281,16 @@ def isSNO(self): self._isSNO = isSNO(self.dynamicClient) return self._isSNO + @logMethodCall + def isAirgap(self): + if self._isAirgap is None: + # First check if the legacy ICSP is installed. If it is raise an error and instruct the user to re-run configure-airgap to + # migrate the cluster from ICSP to IDMS + if isAirgapInstall(self.dynamicClient, checkICSP=True): + self.fatalError("Deprecated Maximo Application Suite ImageContentSourcePolicy detected on the target cluster. Run 'mas configure-airgap' to migrate to the replacement ImageDigestMirrorSet beofre proceeding.") + self._isAirgap = isAirgapInstall(self.dynamicClient) + return self._isAirgap + def setParam(self, param: str, value: str): self.params[param] = value diff --git a/python/src/mas/cli/install/app.py b/python/src/mas/cli/install/app.py index ee6a63384b1..8bd71348457 100644 --- a/python/src/mas/cli/install/app.py +++ b/python/src/mas/cli/install/app.py @@ -978,6 +978,10 @@ def install(self, argv): print_formatted_text(HTML("Error: The Kubernetes dynamic Client is not available. See log file for details")) exit(1) + # Perform a check whether the cluster is set up for airgap install, this will trigger an early failure if the cluster is using the now + # deprecated MaximoApplicationSuite ImageContentSourcePolicy instead of the new ImageDigestMirrorSet + self.isAirgap() + # Configure the installOptions for the appropriate architecture self.catalogOptions = supportedCatalogs[self.architecture] diff --git a/python/src/mas/cli/install/settings/turbonomicSettings.py b/python/src/mas/cli/install/settings/turbonomicSettings.py index 08cee7ca9ff..71a2b528c80 100644 --- a/python/src/mas/cli/install/settings/turbonomicSettings.py +++ b/python/src/mas/cli/install/settings/turbonomicSettings.py @@ -8,8 +8,6 @@ # # ***************************************************************************** -from mas.devops.mas import isAirgapInstall - class TurbonomicSettingsMixin(): @@ -21,7 +19,7 @@ def configTurbonomic(self) -> None: " - Learn more: https://www.ibm.com/products/turbonomic" ]) - if isAirgapInstall(self.dynamicClient): + if self.isAirgap(): self.printHighlight("The Turbonomic Kubernetes Operator does not support disconnected installation at this time") elif self.yesOrNo("Configure IBM Turbonomic integration"): self.promptForString("Turbonomic Target Name", "turbonomic_target_name") diff --git a/python/src/mas/cli/install/summarizer.py b/python/src/mas/cli/install/summarizer.py index 02520b1545a..f2c3dd30f40 100644 --- a/python/src/mas/cli/install/summarizer.py +++ b/python/src/mas/cli/install/summarizer.py @@ -11,7 +11,6 @@ import logging import yaml from prompt_toolkit import print_formatted_text, HTML -from mas.devops.mas import isAirgapInstall from mas.devops.ocp import getConsoleURL logger = logging.getLogger(__name__) @@ -46,7 +45,7 @@ def masSummary(self) -> None: print() self.printSummary("Operational Mode", operationalModeNames[self.operationalMode]) - if isAirgapInstall(self.dynamicClient): + if self.isAirgap(): self.printSummary("Install Mode", "Disconnected Install") else: self.printSummary("Install Mode", "Connected Install") diff --git a/python/src/mas/cli/update/app.py b/python/src/mas/cli/update/app.py index 3d669fb6e9a..157499c469b 100644 --- a/python/src/mas/cli/update/app.py +++ b/python/src/mas/cli/update/app.py @@ -90,6 +90,9 @@ def update(self, argv): if self.dynamicClient is None: self.fatalError("The Kubernetes dynamic Client is not available. See log file for details") + # Perform a check whether the cluster is set up for airgap install, this will trigger an early failure if the cluster is using the now + # deprecated MaximoApplicationSuite ImageContentSourcePolicy instead of the new ImageDigestMirrorSet + self.isAirgap() self.reviewCurrentCatalog() self.reviewMASInstance()