Installing IBM Cloud Pak for Network Automation Orchestration Manager

You can install the Cloud Pak by using the OpenShift® Container Platform console or the Red Hat OpenShift command-line interface (CLI).

Before you begin

Complete the steps in Preparing to install IBM® Cloud Pak for Network Automation Orchestration Manager.

For any steps that use the Red Hat® OpenShift Container Platform CLI, run the oc login command to log in to your Red Hat OpenShift cluster.

Install the Cloud Pak

You can install IBM Cloud Pak for Network Automation Orchestration Manager with either of the following methods:

Install the Cloud Pak with the OpenShift Container Platform console
Install the Cloud Pak with the OpenShift CLI

Customizing your CLI install:

Site Planner is an optional component that is not installed by default. To install this component when the Cloud Pak is installed, you must modify the custom resource that you use to create your instance of IBM Cloud Pak for Network Automation Orchestration Manager.

Similarly, you might want to customize the installation settings if you are installing the Cloud Pak in a production environment. The default settings for CPU, memory, and replicas are for a starter environment.

For more information, see Create the instance with a custom resource.

To access the UI when the Cloud Pak is installed, see Logging in to the IBM Cloud Pak console.

Install the Cloud Pak with the OpenShift Container Platform console

Complete the following steps to install the Cloud Pak:

Install the operator.
Create an instance of IBM Cloud Pak for Network Automation Orchestration Manager.

1. Install the operator.

Log in to your OpenShift Container Platform cluster console.
From the navigation menu, click Operators > OperatorHub.
In the All Items field, enter IBM Cloud Pak for Network Automation Orchestration Manager to search for the Cloud Pak.
Click the IBM Cloud Pak for Network Automation Orchestration Manager tile.
The IBM Cloud Pak for Network Automation Orchestration Manager page is shown.
Click Install.
The Install Operator page is shown.

Select the installation mode that you require from the Installation mode options, then follow the required action in the following table:

Installation mode	Action
A specific namespace on the cluster	From the Installed Namespace list, select the namespace that you created in the preparation step Create a custom namespace.
All namespaces on the cluster	Make sure that you already created the `ibm-common-services` namespace in the preparation step Create the ibm-common-services namespace.

Accept the default values for the other fields and click Install.

2. Create an instance.

Restrictions:

You can create only one IBM Cloud Pak for Network Automation Orchestration Manager instance per namespace.
The instance must be created in the same namespace where you installed the IBM Cloud Pak for Network Automation Orchestration Manager operator.

From the OpenShift Container Platform console, click Operators > Installed Operators.
From the Project list, select the project that you want to create the instance in.
A project is a Kubernetes namespace. Select the namespace that you created in the step Create a custom namespace.
From the list of installed operators, click IBM Cloud Pak for Network Automation Orchestration Manager.
Under Provided APIs, locate the Orchestration tile, and click Create Instance.
The default Form view is shown.
Optional: If you want to create the instance by using a custom resource, click YAML view. Modify the YAML for optional features, storage settings, backups, multitenancy, and other settings. For more information about the settings, read steps 8 to 13 in this procedure.
Review the license agreement, then set the spec.license.accept attribute to true if you agree with the license terms.

Then go to step 15 in this procedure.
Enter the name that you want your instance to be called.
Review the license agreement.
Optional: Click Optional Features.
1. If your deployment requires Site Planner, set Site Planner to true.
Click Storage and set the storage class and storage size for your services.
Tip: If the storage class is not set, the default storage class that is set on the cluster is used. However, if the default storage class is not set on the cluster, you must set the storage class when you are installing the Cloud Pak.
Note:
- In the Zen Block storage configuration, set the storage class name to the name of a block storage class that is present on your cluster, such as rook-ceph-block or lvms-vg1.
- In the Zen File storage configuration, set the storage class name to the name of a file storage class that is present on your cluster, such as rook-cephfs or lvms-vg1.
Optional: Click Backup and configure the backup and restore settings for your instance.
Click Advanced and configure settings such as amount of CPU, memory, and number of replicas for each of your services. You might want to configure the advanced settings if you are installing the Cloud Pak in a production environment. The default settings are for a starter environment.
Optional: To enable multitenancy, click Advanced then set the multitenant attribute to true. If you enable multitenancy mode, then later disable it, the data that is created by users when they were in tenants is no longer available to the users.
Optional: To customize the properties of the OpenSearch service, click Advanced and modify the OpenSearch settings, such as the index name and the number of replicas and shards. OpenSearch is used to store and index application log data and is installed automatically when you install the Cloud Pak.
Important: You cannot easily change the number of primary shards for an index that already contains data. Therefore, configure the number of shards that you need, based on your storage requirements, before you install the Cloud Pak. For more information, see Custom resources.
Optional: Add customized hostnames to access the Cloud Pak services.
- Instead of using the default Red Hat OpenShift hostnames to access the zen, ishtar, nimrod, siteplanner, vault, and opensearch services, you can specify customized hostnames to access these services.
- Click Advanced, open the route settings and specify the ingress domain and the customized hostnames that you want to use. For more information, see Custom resources.
Click Create.
The instance might take some time to create. You can monitor the progress on the Orchestration tab. While the task is running, you might see status values such as Waiting for IBM Cloud Pak foundational services.
To verify that the instance is successfully created, view the status of the instance on the All Instances tab. Your instance is ready when you see the Succeeded status.
Optional: If you created a customized ingress domain, and you want to use a customized hostname for the IBM Cloud Pak console, you must update the hostname for the console's route. The hostname that you use must include your customized domain name. For detailed steps, see Updating custom hostname and TLS secret by using a configmap.

Install the Cloud Pak with the Red Hat OpenShift CLI.

Complete the following steps to install the Cloud Pak:

Install the operator.
Create the instance with a custom resource.

1. Install the operator.

Create a YAML file and add the following resource definition. Replace <namespace> with the namespace that you created in the step Create a custom namespace.

apiVersion: operators.coreos.com/v1alpha2
kind: OperatorGroup
metadata:
  name: ibm-tnc-orchestration-catalog-group
  namespace: <namespace>
spec:
  targetNamespaces:
    - <namespace>

Run the following command, replacing <filename> with the file that you created in step 1:
```
oc create -f <filename>
```

Create another YAML file and add the following resource definition. Replace <namespace> with the namespace from step 1.

apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
    name: ibm-tnc-orchestration-subscription
    namespace: <namespace>
spec:
    channel: v2.7 
    name: ibm-tnc-orchestration-operator
    source: ibm-operator-catalog
    sourceNamespace: openshift-marketplace

Run the following command, replacing <filename> with the file that you created in step 3:
```
oc create -f <filename>
```
After a few minutes, the IBM Cloud Pak for Network Automation Orchestration Manager operator is installed.
Verify that the operator is installed and running. Replace <namespace> with the namespace from step 1.
```
oc get deployment -n <namespace>
```
If the operator is installed and running, the following information is included in the output:
```
ibm-tnc-orchestration-controller-manager          1/1     1            1           76s
```

Create the instance with a custom resource.

Create a YAML file and add the custom resource (CR).
The following example CR is used to create a default instance of IBM Cloud Pak for Network Automation Orchestration Manager. The license acceptance must be specified. All the other keys, such as cpu, memory, and replicas, that are not specified in the CR, use the default settings.

Important:
The default CR settings for CPU, memory, and replicas are for a starter instance.
```
apiVersion: tnc.ibm.com/v1beta1
kind: Orchestration
metadata:
  name: <instance_name>
  namespace: <namespace> 
spec:
  license:
    accept: <license_acceptance>
  version: 2.7.6
```
Where:
- <instance_name> is the name that you want your instance of IBM Cloud Pak for Network Automation Orchestration Manager to be called.
- <namespace> is the namespace that you created in the step Create a custom namespace.
- <license_acceptance> - set to true to accept the license.
Customizing the CR for your environment: In some scenarios, you might want to customize the CR. For example:
- For production environments, you might want to increase the settings for CPU, memory, and replicas for the microservices. For example, you might want to increase the number of pod replicas to three for the Ishtar microservice.
- If the storage class is not set in the CR, the default storage class that is set on the cluster is used. However, if the default storage class is not set on the cluster, you must set the storage class in the CR. For more information about setting the storage class, see Custom resource structure and settings.
- Site Planner is not installed by default. To install the optional component when the instance is created, set the appropriate key in the custom resource to true. For example, set the following key to install the site planner:
```
  featureconfig:
    siteplanner: true
```
- Application logging is enabled automatically when you install the Cloud Pak. To disable application logging during an installation, set the spec.featureconfig.logging attribute to false as follows:
```
spec:
  featureconfig:
    logging: false
```
For more information and examples, see Custom resources.
In the CR, in the zenBlock and zenFile storage configuration, set the storage classes.
- Set the zenBlock.storageClassName attribute to the name of a block storage class that is present on your cluster, such as rook-ceph-block or lvms-vg1.
- Set the zenFile.storageClassName attribute to the name of a file storage class that is present on your cluster, such as rook-cephfs or lvms-vg1.
Optional: To enable multitenancy, set the spec.advanced.multitenant attribute to true. If you enable multitenancy mode, then later disable it, the data that is created by users when they were in tenants is no longer available to the users.
Optional: Customize the OpenSearch settings.
OpenSearch is used to store and index application log data and is installed automatically when you install the Cloud Pak. You can update the default OpenSearch settings, such as the index name, the number of index replicas, and the number of primary index shards, in the spec.advanced.opensearch subsection.
Important: You cannot easily change the number of primary shards for an index that already contains data. Therefore, configure the number of shards that you need, based on your storage requirements, before you install the Cloud Pak. For more information, see Custom resources.
Optional: Add customized hostnames to access the Cloud Pak services.
- Instead of using the default Red Hat OpenShift hostnames to access the zen, ishtar, nimrod, siteplanner, vault, and opensearch services, you can specify customized hostnames to access these services.
- In the spec.advanced.routeSetting section, specify the ingress domain and the customized hostnames that you want to use. For more information, see Custom resources.
Create the instance by running the following command, replacing <filename> with the file that you created in step 1.
```
oc create -f <filename>
```
Run the following command to verify that your instance of IBM Cloud Pak for Network Automation Orchestration Manager is successfully created. Replace <namespace> with the namespace from step 1.
```
oc get orchestration -n <namespace>
```
The instance might take some time to create. When the Status value is Ready, your instance is created.
Optional: If you created a customized ingress domain, and you want to use a customized hostname for the IBM Cloud Pak console, you must update the hostname for the console's route. The hostname that you use must include your customized domain name. For detailed steps, see Updating custom hostname and TLS secret by using a configmap.

What to do next

Complete the following tasks after you install IBM Cloud Pak for Network Automation:

Configure your users' access control permissions

You must have administrator permissions to configure users. To configure your users and their access permissions, complete one of the following items:

If you don't want to use object-based access control (OBAC), configure an LDAP connection for your Red Hat OpenShift cluster. Then map users and user groups from your LDAP directory into the cluster and set the access permissions of users and user groups. For more information, see Configuring an LDAP connection, Mapping users to LDAP roles and groups, and IBM Cloud Pak Managing users.
If you don't want to use LDAP, SAML and OIDC are available with IBM Cloud Pak foundational services. For more information, see IBM Cloud Pak foundational services Authentication types.
If you want to use OBAC, spend some time planning the structure of your object groups and user groups.
In IBM Cloud Pak for Network Automation, you can use object groups, user groups, and users to specify different access control settings for your assembly instances, deployment locations, infrastructure keys, network packages, and secret groups. You can also set the permissions that apply to the user groups.

You can assign several user groups to each object group. You can also assign users to multiple user groups. When you set permissions for the user groups, you must consider how you want to structure access to objects.

When you implement your object groups and user groups, you can follow these steps:
1. Decide which types of user your IBM Cloud Pak for Network Automation deployment needs to support. For example, you might need users who can only read all objects, users who can also create and update some types of object, users who can do most administrative tasks, and users who can do all administrative tasks, including creating object groups. You can then define the permissions for each type of user.
2. Decide how you want to place the objects in object groups and what type of access to give the different types of user to the object groups. These decisions help to determine which user groups you need to create.
3. Create the user groups that allow the user types the access they require. Two levels of permission apply:
  - Role-based access control (RBAC) permissions, which apply to user groups and roles. Users are assigned user groups and roles. To set RBAC permissions, click Administration > Access control from the navigation menu in the IBM Cloud Pak console.
  - Object-based access control (OBAC) permissions, which apply to object groups.
  To use an OBAC permission, a user must have the corresponding RBAC permission. You can give an OBAC permission to a user, but if they don't have the corresponding RBAC permission, the OBAC permission doesn't work.
  For more information about how to create user groups, see Mapping users to LDAP roles and groups.
4. Create the object groups and assign the user groups that you created to each object group. Before you assign a user group to an object group, the permissions must be already set in the user group. For more information, see Managing object groups.
  Before you create your object groups, consider creating an extra administrative role that can't create object groups. You might want to restrict the permission to create object groups to administrators with full permissions.
  When you plan your object groups and user groups, consider associating each user group with a set of permissions for only one object group. For example, you might create the following groups:
  - An object group that is called North.
  - A user group that is called North_FullAdmin and has full read, write, update, and delete permissions to only the North object group.
  - A second user group that is called North_ReadOnly and has read-only permissions to only the North object group.
  By using this convention, you can easily identify what permissions a user has. To identify the permissions, view the user groups in a user's details.
5. Add users to the user groups. You can complete this step in an LDAP directory, then configure an LDAP connection to your Red Hat OpenShift cluster. For more information, see Configuring an LDAP connection.

Configure multitenancy

You can enable multitenancy and configure tenant administrators and users after you install IBM Cloud Pak for Network Automation. For more information, see Configuring multitenancy.

Log in to IBM Automation

Log in to the IBM Automation UI to access IBM Cloud Pak for Network Automation features, such as the orchestration and Site Planner components.

See Logging in to the IBM Cloud Pak console.

Deploy resource drivers

Before you can use the orchestration component to automate your lifecycle processes, you must deploy the resource drivers. Resource drivers run lifecycle and operation requests from the orchestration component. See Resource drivers.