Importing an operator collection

1. Define a z/OS® endpoint.

If the z/OS® endpoints that you will map the operator collection to are already defined, go to the next step.

1. Log in to the z/OS Cloud Broker instance within the namespace you wish to add a z/OS endpoint to. (See Logging in to z/OS Cloud Broker.)

2. In the z/OS Cloud Broker navigation pane, select Manage z/OS endpoints.

   

3. On the "Configure z/OS endpoints" page, select Create endpoint.

   

4. On the "z/OS endpoint configuration" page, define an endpoint as follows:

   

   1. In the z/OS Endpoint name field, enter a name for the endpoint.
   2. For z/OS Endpoint type, select a type for the endpoint. Select Local if the uploaded collection does not require an SSH connection to a remote host. A local endpoint does not require a host and port. Otherwise, select Remote.
   3. In the z/OS Endpoint description field, enter a description for the endpoint.
   4. In the Host field, enter the hostname or IP address of the z/OS system that you are connecting to.
   5. In the Port field, specify the SSH port for the z/OS system.
   6. If variables need to be defined for the endpoint, select Add variable and specify the variable information.
      
      Important: If you are importing the IBM z/OS Package Manager collection, and authentication is required for the registry or registry proxy associated with the collection, you must create a credential Secret in OpenShift. For more information, see Installing z/OS Package Manager.

5. Select Submit.

6. Select Submit again on the "z/OS Endpoint configuration warning" dialog.

   

Step result: The z/OS endpoint is listed on the "Configure z/OS endpoints" page.

Note: z/OS® Cloud Broker license usage is based on the number of z/OS endpoints defined in z/OS® Cloud Broker. For more information, see Tracking z/OS Cloud Broker license usage.

2. Import an operator collection.

You can choose from three methods to import an operator collection: from an Ansible Galaxy operator collection catalog, from a specified URL, or by manual upload. Screenshots are provided to illustrate some step instructions. Although some screenshots use IBM z/OS Package Manager Collection as an example, the process is the same for all operator collections. For air-gapped Red Hat OpenShift environments, see Installing operator collections in air-gapped environments.

1. In the z/OS Cloud Broker navigation pane, select Import operator collections.

   

2. On the "Import operator collections" page, use one of the following methods to upload an operator collection:

   • By importing from an Ansible Galaxy operator collection catalog:

     1. Select Operator catalog.

     2. (Optional) Configure your Ansible Galaxy URL by completing the following steps:

        1. Select Configuration.
           
           

        2. Replace the default URL with your custom URL in the Enter URL field.

        3. Select Test. If the test fails, update the URL and test again.
           
           

        4. Select Save if the test passes.
           
           

           If the configuration is successful, a success message is displayed.
           
           

     3. Select the collections that you want to import from the operator catalog. You can import IBM-supplied operator collections or operator collections provided by the community. Currently, IBM provides the following operator collections:

        • The IBM z/OS Package Manager Collection includes playbooks to automate the installation and management of the z/OS Package Manager on a z/OS endpoint. For more information, see IBM z/OS Package Manager.
        • The IBM IMS Operator Collection includes roles and playbooks used for provisioning IMS on a Wazi sandbox. For more information, see IBM IMS Operator.
        • The IBM CICS TS Operator Collection can be used to provision and manage instances of CICS TS regions in virtual z/OS environments. For more information, see IBM CICS TS Operator.

     4. Select Next.

     5. On the Upload public key and signature files tab, for each collection, do one of the following:
        
        

        • Upload the collection public key and signature file to validate the operator collection by completing the following steps:

          1. Select the version to import in the Version field.

          2. Select Download public keys and signature files to access the corresponding operator release page in GitHub for the operator collection being imported, as in the following example.
             
             

          3. In the Assets column on that page, select the file ending in .pub to download the public key and the file ending in .sig to download the signature file, as in the following example.
             
             

          4. Back on the Upload public key and signature files tab, select Upload, and select the public key you just downloaded from GitHub.

          5. Select Upload again and select the signature file you just downloaded from GitHub.

        • Check the I want to skip validation checkbox.
          
          Note: It is recommended that you validate the operator collection by uploading the associated public key and signature file. If you opt to skip this step, you may run the risk of importing an operator collection that has been tampered with.

     6. Select Import.

   • By importing from a specified URL:

     1. Select URL.

     2. On the Collection information tab:
        
        

        1. Enter the URL for the operator collection (including the name of the .tar file) in the URL field.
        2. If the operator collection is in a private Github repository, check the Authorization field checkbox and specify your GitHub access token in the GitHub token field.
        3. Select Next.

     3. On the Upload public key and signature files tab, do one of the following:
        
        

        • Upload an IBM provided public key and signature file to validate the operator collection by completing the following steps:

          1. Select Download public keys and signature files to access the IBM Z & Cloud Modernization Stack Github community page .

          2. Navigate to the operator release page associated with the operator collection being imported.

          3. In the Assets column, select the file ending in .pub to download the public key and the file ending in .sig to download the signature file.
             
             

          4. Back on the Upload public key and signature files tab in z/OS® Cloud Broker, select Add key and select the public key you just downloaded from GitHub.

          5. Select Add signature and select the signature file you just downloaded from GitHub.

          6. Select Next.

        • Check the I accept the risks associated with skipping this step. checkbox and then select Skip.
          
          Note: It is recommended that you validate the operator collection by uploading the associated public key and signature file. If you opt to skip this step, you may run the risk of importing an operator collection that has been tampered with.

     4. On the Review & import collection tab, do one of the following:

        • If you uploaded public key and signature files on the previous tab:

          1. Review the collection information details, including those included in the Public key and Signature file fields.
             
             

          2. If all details look correct, select Import.

        • If you opted to skip uploading of public key and signatures files on the previous tab:

          1. Review the Operator collection validation warning.
             
             

          2. If you wish to accept the risks of not completing operator collection validation and continue, select Import.

   • By importing a manually uploaded collection:

     1. Select Upload.

     2. On the Collection information tab:
        
        

        1. Select Add file.
        2. Select the operator collection (of file type .tar, .tar.gz or .tgz) to import.
        3. Select Next.

     3. On the Upload public key and signature files tab, do one of the following:
        
        

        • Upload an IBM provided public key and signature file to validate the operator collection by completing the following steps:

          1. Select Download public keys and signature files to access the IBM Z & Cloud Modernization Stack Github community page .

          2. Navigate to the operator release page associated with the operator collection being imported.

          3. In the Assets column, select the file ending in .pub to download the public key and the file ending in .sig to download the signature file.
             
             

          4. Back on the Upload public key and signature files tab in z/OS® Cloud Broker, select Add key and select the public key you just downloaded from GitHub.

          5. Select Add signature and select the signature file you just downloaded from GitHub.

          6. Select Next.

        • Check the I accept the risks associated with skipping this step. checkbox and then select Skip.
          
          Note: It is recommended that you validate the operator collection by uploading the associated public key and signature file. If you opt to skip this step, you may run the risk of importing an operator collection that has been tampered with.

     4. On the Review & import collection tab, do one of the following:

        • If you uploaded public key and signature files on the previous tab:

          1. Review the collection information details, including those included in the Public key and Signature file fields.
             
             

          2. If all details look correct, select Import.

        • If you opted to skip uploading of public key and signatures files on the previous tab:

          1. Review the Operator collection validation warning.
             
             

          2. If you wish to accept the risks of not completing operator collection validation and continue, select Import.

Step result: Once the operator collection is successfully imported, it is displayed in the Imported section on the "Configure operator collections" page.

3. Map the operator collection to z/OS endpoints across namespaces to create the operator.

This step ensures that the tasks that are defined in an operator collection are performed against the specified z/OS environments. If the Multi-namespace suboperators functionality is enabled for the z/OS Cloud Broker instance, and z/OS endpoints are specified across selected namespaces during this step, operators will be automatically installed in each namespace and will be able to run against each of the z/OS endpoints.

1. In the z/OS Cloud Broker navigation pane, select Manage operator collections.

   

2. In the Imported section on the "Configure operator collections" page, select the operator collection that you wish to map to one or more z/OS endpoints.

   

3. On the Upload SSH key tab, select one or more z/OS endpoints for this operator collection.

   

   Note: No credentials are needed for local endpoints. If you are mapping only local endpoints, skip the next step. Credentials are applied only to remote endpoints when both endpoint types are selected.

4. Upload your credentials for each z/OS endpoint, do one of the following:

   • Select Shared credentials if you want to use the same credentials across all suboperators. This means that each instance will use the username and SSH key you provide. Using a functional ID is recommended. Complete the following steps:

     1. Click Add key and select an SSH private key for connecting to the z/OS endpoints you are mapping your operator collection to. If you do not already have an SSH key for z/OS, see Creating SSH keys for IBM z/OS Cloud Broker.
        

     2. In the SSH key username field, enter the z/OS username this key has been authorized to be used with.
        
        

     3. If you entered a passphrase during SSH key generation, select Yes under the Provide a SSH key passphrase (optional) field and enter the passphrase.
        
        

     4. Select Test SSH key.
        
        

        If the SSH test is successful, a success message is displayed.

     5. If needed, select one or more z/OS endpoints and click Remove credentials to remove the uploaded credentials.

   • Select Personal credentials if you want the user to provide their personal credentials each time they create an instance of the suboperator. For more information about generating an encrypted credential, see Managing encrypted z/OS Cloud Broker credentials.

   Note: If you select Shared credentials, you will need to do auditing in Openshift to track which user created each instance. If you select Personal credentials, auditing can be performed on the z/OS LPAR. Access can be managed by z/OS sysadmins, instead of using RBAC in Openshift, by granting or denying permissions to various resources via each user's personal ID. If a user attempts to install ZPM without the necessary permissions on z/OS, the instance creation will fail.

5. Select Next.

6. On the Select namespace(s) tab, map one or more namespaces to one or more credential verified z/OS endpoints by completing the following steps:
   
   

   1. Select one or more z/OS endpoints.

   2. Select one or more namespaces.
      
      

   3. Click Add namespace(s) and the selected namespaces are displayed. You can expand the table for a detailed view of the selected namespaces.
      
      

   4. If needed, select one or more z/OS endpoints and click Remove namespace(s) to remove the selected namespaces.

   Note: At least one namespace should be added to each z/OS endpoint. To prevent mapping failures, avoid mapping the operator collection to a target namespace if it has already been mapped to by an operator from another namespace.

7. Click Next.

8. Review the mapping details on the Review and confirm tab and then select Submit.

   

   If the configuration is successful, a success message is displayed.

   

Step result: The operator collection is mapped to the z/OS endpoints across the specified namespaces and is listed in the Configure collections section on the "Configure operator collections" page.