Installing the management subsystem

Install the managment subsystem by creating and applying the ingress-issuer and mgmt_cr YAML files.

Before you begin

When installing subsystems in different namespaces you must first create the cert-manager issuers and certificates required by that subsystem in the same namespace.

Create a file called ingress-issuer-management.yaml and paste in the following:

#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
# 
#     http://www.apache.org/licenses/LICENSE-2.0
# 
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#

---

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: selfsigning-issuer
  labels:
    app.kubernetes.io/instance: management
    app.kubernetes.io/managed-by: ibm-apiconnect
    app.kubernetes.io/name: selfsigning-issuer
spec:
  selfSigned: {}
---
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: ingress-issuer
  labels:
    app.kubernetes.io/instance: management
    app.kubernetes.io/managed-by: ibm-apiconnect
    app.kubernetes.io/name: ingress-issuer
spec:
  ca:
    secretName: ingress-ca
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: ingress-ca
  labels:
    app.kubernetes.io/instance: management
    app.kubernetes.io/managed-by: ibm-apiconnect
    app.kubernetes.io/name: ingress-ca
spec:
  secretName: ingress-ca
  commonName: "ingress-ca"
  usages:
  - digital signature
  - key encipherment
  - cert sign
  isCA: true
  duration: 87600h # 10 years
  renewBefore: 720h # 30 days
  privateKey:
    rotationPolicy: Always
  issuerRef:
    name: selfsigning-issuer
    kind: Issuer
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: portal-admin-client
  labels: 
    app.kubernetes.io/instance: management
    app.kubernetes.io/managed-by: ibm-apiconnect
    app.kubernetes.io/name: portal-admin-client
spec:
  subject:
    organizations:
    - cert-manager
  commonName: portal-admin-client
  secretName: portal-admin-client
  issuerRef:
    name: ingress-issuer
  usages:
  - "client auth"
  - "signing"
  - "key encipherment"
  duration: 17520h # 2 years
  renewBefore: 720h # 30 days
  privateKey:
    rotationPolicy: Always
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: gateway-client-client
  labels:
    app.kubernetes.io/instance: management
    app.kubernetes.io/managed-by: ibm-apiconnect
    app.kubernetes.io/name: gateway-client-client
spec:
  subject:
    organizations:
    - cert-manager
  commonName: gateway-client-client
  secretName: gateway-client-client
  issuerRef:
    name: ingress-issuer
  usages:
  - "client auth"
  - "signing"
  - "key encipherment"
  duration: 17520h # 2 years
  renewBefore: 720h # 30 days
  privateKey:
    rotationPolicy: Always
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: analytics-ingestion-client
  labels:
    app.kubernetes.io/instance: management
    app.kubernetes.io/managed-by: ibm-apiconnect
    app.kubernetes.io/name: analytics-ingestion-client
spec:
  subject:
    organizations:
    - cert-manager
  commonName: analytics-ingestion-client
  secretName: analytics-ingestion-client
  issuerRef:
    name: ingress-issuer
  usages:
  - "client auth"
  - "signing"
  - "key encipherment"
  duration: 17520h # 2 years
  renewBefore: 720h # 30 days
  privateKey:
    rotationPolicy: Always

Apply the YAML file with: oc apply -f ingress-issuer-management.yaml -n <management namespace>

Confirm that the issuers were created and are in ready state:


oc get issuers -n <management namespace>
NAME                 READY
ingress-issuer       True
selfsigning-issuer   True

Procedure

Create a file that is called mgmt_cr.yaml and paste in the following content:

#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#


apiVersion: management.apiconnect.ibm.com/v1beta1
kind: ManagementCluster
metadata:
  name: management
  labels:
    app.kubernetes.io/instance: management
    app.kubernetes.io/managed-by: ibm-apiconnect
    app.kubernetes.io/name: management
  annotations:
    apiconnect-operator/cp4i: "false"
spec:
  version: $APP_PRODUCT_VERSION
  profile: $PROFILE
  portal:
    admin:
      secretName: portal-admin-client
  analytics:
    ingestion:
      secretName: analytics-ingestion-client
  gateway:
    client:
      secretName: gateway-client-client
  cloudManagerEndpoint:
    annotations:
      cert-manager.io/issuer: ingress-issuer
    hosts:
    - name: admin.$STACK_HOST
      secretName: cm-endpoint
  apiManagerEndpoint:
    annotations:
      cert-manager.io/issuer: ingress-issuer
    hosts:
    - name: manager.$STACK_HOST
      secretName: apim-endpoint
  platformAPIEndpoint:
    annotations:
      cert-manager.io/issuer: ingress-issuer
    hosts:
    - name: api.$STACK_HOST
      secretName: api-endpoint
  consumerAPIEndpoint:
    annotations:
      cert-manager.io/issuer: ingress-issuer
    hosts:
    - name: consumer.$STACK_HOST
      secretName: consumer-endpoint
  consumerCatalogEndpoint:
    annotations:
      cert-manager.io/issuer: ingress-issuer
    hosts: 
    - name: consumer-catalog.myhost.subnet.example.com
      secretName: consumer-catalog-endpoint
  databaseVolumeClaimTemplate:
    storageClassName: $STORAGE_CLASS
  microServiceSecurity: certManager
  certManagerIssuer:
    name: selfsigning-issuer
    kind: Issuer
  license:
    accept: $LICENSE_ACCEPTANCE
    use: $LICENSE_USE
    license: '$LICENSE_ID'

Edit the YAML file and replace the variables:
$APP_PRODUCT_VERSION
API Connect application version for the subsystems.
```
version: <version_number>
```
Example version number: 10.0.9.0
$PROFILE

Specify your management subsystem profile, where n indicates number of replicas, c number of cores, and m is the minimum memory allocation in GB. For more information on profiles, see Deployment and component profiles.

$STACK_HOST
The desired ingress subdomain for the API Connect stack. Used when specifying endpoints. Domain names that are used for endpoints cannot contain the underscore "_" character. You can do one of the following:
- Subdomain customization only
  Accept the prefixes predefined for the ingress host names to use and replace all instances of STACK_HOST to be the desired ingress subdomain for the API Connect stack. For example, if your host is myhost.subnet.example.com:
  
  cloudManagerEndpoint: < ... > hosts: - name: admin.myhost.subnet.example.com secretName: cm-endpoint apiManagerEndpoint: < ... > hosts: - name: manager.myhost.subnet.example.com secretName: apim-endpoint platformAPIEndpoint: < ... > hosts: - name: api.myhost.subnet.example.com secretName: api-endpoint consumerAPIEndpoint: < ... > hosts: - name: consumer.myhost.subnet.example.com secretName: consumer-endpoint consumerCatalogEndpoint: < ... > hosts: - name: consumer-catalog.myhost.subnet.example.com secretName: consumer-catalog-endpoint
- Complete hostname customization
  Change both the predefined prefixes and the STACK_HOST subdomain to match your desired hostnames.
  
  For example, for cloudManagerEndpoint, you can replace admin.$STACK_HOST with my.cloudmgr.myhost.subnet.example.com, where my.cloudmgr replaces admin, and myhost.subnet.example.com replaces STACK_HOST. For example:
  
  cloudManagerEndpoint: < ... > hosts: - name: my.cloudmgr.myhost.subnet.example.com secretName: cm-endpoint
  You can do this for some or all of the host names, depending on your customization requirements.
$STORAGE_CLASS
The OCP storage class to be used for Persistent Volume Claims. Find the available storage classes in the target cluster by running the following command: oc get sc.
```
storageClassName: local-storage
```
$LICENSE_ACCEPTANCE

Set accept to true. You must accept the license to successfully deploy API Connect.

$LICENSE_USE

Set use to either production or nonproduction to match the license that you purchased.

$LICENSE_ID

Set license: to the license ID for the version of API Connect that you purchased. See API Connect licenses.
Optional: If Cloud Pak for Integration is installed, and you want your API Connect installation to be integrated with it, then set metadata.annotations.apiconnect-operator/cp4i to true.

This annotation enables integration with Cloud Pak for Integration.
Install the management subsystem by applying the modified CR with the following command:
```
oc apply -f mgmt_cr.yaml -n <management_namespace>
```

Verify that the management subsystem is fully installed by running the following command:

oc get ManagementCluster -n <management_namespace>

The installation is complete when the READY status is True, and the SUMMARY reports that all services are online:

NAME         READY   SUMMARY   VERSION    RECONCILED VERSION   AGE
management   True   16/16       <version>   <version-build>       7m17s

Verify that you can log in to the API Connect Cloud Manager UI:
1. Determine the URL for the Cloud Manager UI by running the following command to view the API Connect endpoints:
```
oc get routes -n <management_namespace>
```
2. Locate the management-admin endpoint, and note it down.
3. Determine the Cloud Manager administrator password by running the following commands:
```
oc get secret -n <management-namespace> | grep management-admin-secret

oc get secret -n <management-namespace> <secret_name_from_previous command> -o jsonpath="{.data.password}" | base64 -d && echo ""
```
4. Open a browser and go to the management-admin-apic endpoint.
5. Log in to the Cloud Manager as admin with the administrator password.
Store all secrets and passwords in a safe place.
Backup your management subsystem database and infrastructure configuration: Backing up and restoring the management subsystem.
For more information about advanced configuration for Postgres components, see Advanced configuration for Postgres components on Kubernetes V10.0.7.0 and later.

What to do next

If you are creating a new deployment of API Connect, install other subsystems as needed.

When you have completed the installation of all required API Connect subsystems, you can proceed to defining your API Connect configuration by using the API Connect Cloud Manager; refer to the Cloud Manager configuration checklist.