Manual installation on Kubernetes from scratch with `kubectl`

Learn how to install License Service from scratch on Kubernetes with kubectl.

The support for this version of License Service is being sunset by the end of 2024. Install the newest License Service version. To learn how to install the newest version of License Service, see Installing License Service.

Prerequisites
Installation
Creating an IBM Licensing instance
Configuring ingress
Verification

Prerequisites

Administrator permissions for the cluster.
kubectl version 1.25 or higher.
Linux or iOS.

Before installation, see Preparing for installation to check the installation requirements.

Installation

Note: This procedure guides you through the installation of License Service. It does not cover the installation of License Service Reporter, which is not available without an an IBM Cloud Pak® on OpenShift Container Platform.

Note: To install License Service on Windows, adjust the commands to fit the Windows standard.

Install the Operator Lifecycle Manager (OLM).
1. Make sure that you are connected to your cluster. You can run the following command:
```
kubectl get node
```
  The response should contain a list of your nodes.
2. Check if you have OLM installed, for example, by running the following command:
```
kubectl get crd clusterserviceversions.operators.coreos.com
```
  - If you get the following response, OLM is installed.
```
NAME                                          CREATED AT
clusterserviceversions.operators.coreos.com   2020-06-04T14:42:13Z
```
  - If you get the following response, OLM CRD is not installed. Continue with the following step.
```
Error from server (NotFound): customresourcedefinitions.apiextensions.k8s.io "clusterserviceversions.operators.coreos.com" not found
```
3. If OLM is not installed, download it from the OLM GitHub repository. Use the following script to download and install OLM v0.19.1
  
  Note: For versions newer than 0.19.1, the process might differ.
```
olm_version=v0.19.1
curl -sL https://github.com/operator-framework/operator-lifecycle-manager/releases/download/${olm_version}/install.sh | bash -s ${olm_version}
```
  Troubleshooting: If you get an error, you might have the outdates version of Kubernetes. You can try either upgrading your Kubernetes server version or using older version of OLM.

Create the CatalogSource.

To get GLOBAL_CATALOG_NAMESPACE, check global catalog namespace in a yaml in a packageserver OLM pod that is somewhere on your cluster. You can, for example, use the following command:

olm_namespace=$(kubectl get csv --all-namespaces -l olm.version -o jsonpath="{.items[?(@.metadata.name=='packageserver')].metadata.namespace}")
GLOBAL_CATALOG_NAMESPACE=$(kubectl get deployment --namespace="${olm_namespace}" packageserver -o yaml | grep -A 1 -i global-namespace | tail -1 | cut -d "-" -f 2- | sed -e 's/^[ \t]*//')
# check if the namespace is found
echo ${GLOBAL_CATALOG_NAMESPACE}

If you get an empty response to the echo command, you can get global catalog namespace using the following command.

Note: The following method should only be used for getting global catalog namespace if the previous method failed.

GLOBAL_CATALOG_NAMESPACE=$(kubectl get pod --all-namespaces -l app=olm-operator -o jsonpath="{.items[0].metadata.namespace}")
echo ${GLOBAL_CATALOG_NAMESPACE}

Create the CatalogSource by using the following command:

cat <<EOF | kubectl apply -f -
apiVersion: operators.coreos.com/v1alpha1
kind: CatalogSource
metadata:
  name: opencloud-operators
  namespace: $GLOBAL_CATALOG_NAMESPACE
spec:
  displayName: IBMCS Operators
  publisher: IBM
  sourceType: grpc
  image: icr.io/cpopen/ibm-operator-catalog
  updateStrategy:
    registryPoll:
      interval: 45m
EOF

Check the results.

Run the following command to check if the CatalogSource is created in the $GLOBAL_CATALOG_NAMESPACE namespace:

kubectl get catalogsource -n $GLOBAL_CATALOG_NAMESPACE

The following is the sample output:

NAME                           DISPLAY                        TYPE   PUBLISHER   AGE
opencloud-operators            IBMCS Operators                grpc   IBM         20m
[...]

If everything goes well, you should see similar pod running. Run the following command to check if the pod is running:

kubectl get pod -n $GLOBAL_CATALOG_NAMESPACE

The following is the sample output:

NAME                                            READY   STATUS    RESTARTS   AGE
opencloud-operators-66df4d97ff-4rhjj            1/1     Running   0          80s
[...]

Create an OperatorGroup.

An OperatorGroup is used to denote which namespaces your Operator should watch. It must exist in the namespace where your operator is deployed, for example, ibm-common-services.
1. Create a namespace for IBM Licensing with the following command.
```
kubectl create namespace ibm-common-services
```
2. Check if the operator group exists in that namespace by running the following command:
```
kubectl get OperatorGroup -n ibm-common-services
```
3. If you get the following response, the operator group was found, and you can go to step 4 and create a Subscription.
```
NAME            AGE
operatorgroup   39d
```
4. If you get the following response, the operator group was not found, and you need to create it.
```
No resources found.
```
5. Create the operator group.
  
  Use the following command to deploy the OperatorGroup resource.
```
cat <<EOF | kubectl apply -f -
apiVersion: operators.coreos.com/v1
kind: OperatorGroup
metadata:
  name: operatorgroup
  namespace: ibm-common-services
spec:
  targetNamespaces:
  - ibm-common-services
EOF
```

Create a Subscription.

A subscription is created for the operator and is responsible for upgrades of IBM Licensing when needed.

Make sure that the GLOBAL_CATALOG_NAMESPACE variable has the global catalog namespace value. The global catalog namespace was retrieved in step 2.

Create the Subscription using the following command:

cat <<EOF | kubectl apply -f -
apiVersion: operators.coreos.com/v1alpha1
kind: Subscription
metadata:
  name: ibm-licensing-operator-app
  namespace: ibm-common-services
spec:
  channel: v3
  name: ibm-licensing-operator-app
  source: opencloud-operators
  sourceNamespace: $GLOBAL_CATALOG_NAMESPACE
EOF

Verify operator health.

To check whether IBM Licensing is deployed by OLM from the CatalogSource, run the following command.

kubectl get clusterserviceversion -n ibm-common-services -o jsonpath="v{.items[*].spec.version}"

The Output should be the latest IBM Licensing release version. To check the latest IBM Licensing release version, see https://github.com/IBM/ibm-licensing-operator/blob/latest/version/version.go.

The example output:

//
// Copyright 2022 IBM Corporation
//
// 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.
//
package version

var (
         Version = "1.16.6"
)

Note: The above command assumes that you have created the Subscription in the ibm-common-services namespace. If your Operator deployment (CSV) shows Succeeded in the InstallPhase status, the operator is deployed successfully. Otherwise, check the ClusterServiceVersion objects status for details.

Optional: Check if the operator is deployed. Run the following command:

kubectl get deployment -n ibm-common-services | grep ibm-licensing-operator

Results: You have created the Operator for IBM Licensing Service. The Operator is only responsible for watching over the configuration and managing resources used by IBM Licensing Service.

Creating an IBM Licensing instance

Important: The minimal setup requires applying this IBMLicensing instance. However, before applying the instance, get familiar with the entire configuration process.

To create the IBM Licensing instance, run the following command:

cat <<EOF | kubectl apply -f -
apiVersion: operator.ibm.com/v1alpha1
kind: IBMLicensing
metadata:
  name: instance
spec:
  apiSecretToken: ibm-licensing-token
  httpsEnable: true
  instanceNamespace: ibm-common-services
  datasource: datacollector
EOF

Results: Installation is complete and License Service is running in your cluster.

Configuring ingress

This step is required only if you installed License Service on IBM Cloud Kubernetes Services (IKS) or Amazon Elastic Kubernetes Service (EKS). After you complete the installation, configure ingress before you proceed to verification. For detailed instructions, see Configuring ingress.

If you installed License Service on OpenShift Container Platform, proceed to verification.

Verification