ibmcom/ibm-sls repository overview

⁠Introduction

IBM Suite Licensing Service (SLS) Provides an (API) for a licensing system with RLKS as the backend technology.

There are 4 sets of APIs:

• Passthrough APIs provide passthrough APIs to RLKS. The APIs definitions mirror the RLKS client interfaces.
• Entitlement APIs provide the ability to configure and upload entitlements to the licensing system.
• Token Pool APIs provide basic reporting stats on token usage.
• License Mgmt APIs provide license management capabilities.

The token pool and license mgmt APIs require a datastore in order to add persistence, caching, and heartbeat handling for RLKS. The passthrough and entitlement APIs can be used without a datastore.

This is pre-release, in development, software. Do not use this in production, do expect (and report) bugs.

⁠Details

⁠Prerequisites

• Compute architecture required: 64-bit Intel/AMD x86
• Supported cloud type: rhocp4 RedHat OpenShift Container Platform 4

⁠Resources Required

Minimum scheduling capacity:

⁠Install cert-manager

The version of cert-manager available from OperatorHub is out of date, you will need to install cert-manager 1.1.0 (or newer)

oc create namespace cert-manager
oc apply -f https://github.com/jetstack/cert-manager/releases/download/v1.1.0/cert-manager.yaml

For more information refer to the installation instructions⁠

⁠Configure entitlement

Create your namespace, e.g. ibm-sls and create a Docker secret named ibm-entitlement containing your entitlement key for the IBM Entitled Registry.

oc new-project ibm-sls
oc create secret docker-registry ibm-entitlement \
  --docker-server=<your-registry-server> \
  --docker-username=<your-name> \
  --docker-password=<your-pword> \

⁠Configure MongoDb credentials

Create a secret in the namespace where you plan to deploy SLS:

apiVersion: v1
kind: Secret
type: Opaque
metadata:
  name: sls-mongo-credentials
  namespace: ibm-sls
data:
  username: "<base64 encoded username>"
  password: "<base64 encoded password>"

⁠Installing

Install the operator in your newly created namespace and then create an instance of the LicenseService, selecting the appropriate storage class and size. To view a list of available storage classes in your cluster execute the following command: oc get storageclasses

apiVersion: sls.ibm.com/v1
kind: LicenseService
metadata:
  name: sls
  namespace: ibm-sls
spec:
  mongo:
    configDb: admin
    nodes:
      - host: host1.domain.com
        port: 30257
      - host: host2.domain.com
        port: 30257
    secretName: sls-mongo-credentials
  rlks:
    storage:
      class: ibmc-block-bronze
      size: 5G

⁠Verification

Set up port forwarding to expose the internal API outside of the cluster:

oc port-forward service/sls 7000:443

⁠Verify the API is running

curl -ik https://localhost:7000/api/entitlement/config
HTTP/1.1 200 OK
X-Powered-By: Servlet/4.0
Content-Type: application/json
Date: Mon, 12 Oct 2020 08:58:44 GMT
Content-Language: en-GB
Transfer-Encoding: chunked

{"rlks":{"configuration":"single","hosts":[{"id":"0242ac110002","hostname":"rlks-0.rlks","port":27000}]}}

⁠Upload an entitlement File

curl -i -k -X PUT -F "[email protected]" https://localhost:7000/api/entitlement/file
HTTP/1.1 100 Continue
Content-Length: 0
Date: Mon, 12 Oct 2020 08:56:59 GMT

HTTP/1.1 200 OK
Date: Mon, 12 Oct 2020 08:57:18 GMT
X-Powered-By: Servlet/4.0
Content-Length: 0
Content-Language: en-GB

⁠Verify that you can find an expected product type

curl -ik https://localhost:7000/api/products/MAS-Limited
HTTP/1.1 200 OK
X-Powered-By: Servlet/4.0
Content-Type: application/json
Date: Mon, 12 Oct 2020 09:01:17 GMT
Content-Language: en-GB\nTransfer-Encoding: chunked

{"productId":"MAS-Limited","productVersion":"1.0","tokenId":"AppPoints","tokenCost":5,"issuedDate":"2020-04-22T00:00:00Z","expirationDate":"2023-08-30T00:00:00Z"}

⁠Verify that you can retrieve the token pool

curl -ik https://localhost:7000/api/tokens
HTTP/1.1 200 OK
X-Powered-By: Servlet/4.0
Content-Type: application/json
Date: Mon, 12 Oct 2020 09:02:02 GMT
Content-Language: en-GB
Transfer-Encoding: chunked

[{"tokenId":"AppPoints","entitled":100,"used":0,"concurrent":0,"reserved":0,"expirationDate":"2023-08-30T00:00:00Z","available":100,"issuedDate":"2020-04-22T00:00:00Z"}]

⁠Configuration

⁠Storage

When installing the LicenseService instance you will be prompted for the storage class and capacity for a PVC that will be used by the Rational License Key Server (RLKS). There are no specific performance requirements for the storage class and it only requires minimal capacity (less than 1Gb), you may choose the cheapest or lowest quality of service storage class available in your cluster, and set the size to the lowest value supported by the storage class.

A PVC named rlks-pvc will be automatically created, using ReadWriteOnce access mode.

⁠Storage on IBM Cloud

Due to the minimal requirements most storage classes will be supported, but the following IBM Cloud storage classes have been specifically tested with:

• File Gold
• Block Custom

⁠Encryption

We recommend the use of storage with passive encryption enabled to protect your data, no active encyption is performed by the licensing systems that utilize the persistent volume.

⁠Backup

⁠Backup process:

• Backup a snapshot of the mongo database (all collections)
• Make a record of the license id

⁠Restore process:

• Restore the mongo database snapshot (all collections)
• Deploy the licenseservice instance, but provide the addional property licenceId in the custom resource spec which will override the generation of a new ID. This is neccessary to re-use your existing license file.
• Upload the same license file to the restored service

⁠Limitations

• The operator only supports single namespace deployment
• Multiple instances of the operator can be deployed in a single cluster
• Multiple installations of the LicenseServer Instance can be deployed in the same namespace, however we recommend a single instance per namespace

⁠Upgrades

Refer to the official Red Hat documentation for upgrading operators installed using Operator Lifecycle Manager⁠.

⁠SecurityContextConstraints Requirements

This operator requires a SecurityContextConstraints to be bound to the target namespace prior to installation.

The default predefined SecurityContextConstraints (restricted) and the custom SCC below have been verified for this operator. If your target namespace is bound to one of these SecurityContextConstraint resources you can proceed to install the operator.

apiVersion: security.openshift.io/v1
metadata:
  annotations:
    kubernetes.io/description: "This policy is the most restrictive for SLS,
      requiring pods to run with a non-root UID, and preventing pods from accessing the host.
      The UID and GID will be bound by ranges specified at the Namespace level."
  name: ibm-sls-custom-scc
allowHostDirVolumePlugin: false
allowHostIPC: false
allowHostNetwork: false
allowHostPID: false
allowHostPorts: false
allowPrivilegeEscalation: true
allowPrivilegedContainer: false
allowedCapabilities: null
defaultAddCapabilities: null
fsGroup:
  type: MustRunAs
kind: SecurityContextConstraint
priority: 0
readOnlyRootFilesystem: false
requiredDropCapabilities:
- KILL
- MKNOD
- SETUID
- SETGID
runAsUser:
  type: MustRunAsRange
seLinuxContext:
  type: MustRunAs
supplementalGroups:
  type: RunAsAny
users: []
volumes:
- configMap
- downwardAPI
- emptyDir
- persistentVolumeClaim
- projected
- secret