Installing License service

1. Before installing

Consider getting familiar with:
- On-Premise solution architecture
- System requirement
Make sure the necessary preparation steps are completed:
1. Preparation for installation
2. Fetching installation artifacts

Collect the necessary information that was set or retrieved on previous steps:

Object	Example value	How to get value
Urbi License key	`DEMO-KEY-DGCTL-AAAAAA-BBBBBB`	See Preparation for installation
S3 compatible Installation Artifacts Storage endpoint	`artifacts.storage.local`	See Fetching installation artifacts
Installation Artifacts Storage bucket name	`onpremise-artifacts`	See Fetching installation artifacts
Installation Artifacts Storage access key	`AKIAIOSFODNN7EXAMPLE`	See Fetching installation artifacts
Installation Artifacts Storage secret key	`wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY`	See Fetching installation artifacts
Docker Registry server address	`docker.registry.local:5000`	See Fetching installation artifacts
Docker Registry username	`registry`	See Fetching installation artifacts
Docker Registry password	`DOCKERregistryP@ssW0rd`	See Fetching installation artifacts

Make sure that the resource requirements specified in the Helm chart are met. For more information on how to do this, refer to the System requirements document.

Note

Contents of the Helm chart described in this chapter are relevant for the latest On-Premise version (see Release notes). To find parameters for earlier versions, open values.yaml on GitHub and enter the required version number (for example, 1.18.0) in the tag switcher on the left.

2. Install License service

To install License service, use Helm chart. All parameters are described in values.yaml.

To install License service:

Create a Helm configuration file. See here for more details on the available settings. The example is prefilled with the necessary data collected on previous steps.
values-license.yaml
```
dgctlDockerRegistry: ''

dgctlStorage:
    host: artifacts.example.com
    secure: false
    region: ''
    bucket: onpremise-artifacts
    accessKey: AKIAIOSFODNN7EXAMPLE
    secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY

license:
    type: ''
    retryPeriod: 30s
    softBlockPeriod: 2w

ingress:
    enabled: true
    className: nginx
    hosts:
        - host: license.example.com
          paths:
              - path: /
                pathType: Prefix
    tls: []
    #- hosts:
    #  - license.example.com
    #  secretName: secret.tls

persistence:
    host: artifacts.example.com
    secure: false
    region: ''
    bucket: onpremise-artifacts
    root: 'license_state'
    accessKey: AKIAIOSFODNN7EXAMPLE
    secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY

tpm:
    mountTPMDevice: false
    pvcBind:
        enable: false
        storageClassName: ''

customCAs:
    bundle: ''
    # bundle: |
    #   -----BEGIN CERTIFICATE-----
    #   ...
    #   -----END CERTIFICATE-----
    certsPath: ''

resources:
    limits:
        DOMAIN/tpmrm: 1

affinity: {}
```
Where:
- dgctlDockerRegistry: Docker Registry endpoint where On-Premise services' images reside. Example: HOST:PORT.
- dgctlStorage: installation artifacts storage settings.
  - Fill in the common settings to access the storage: endpoint, bucket, and access credentials.
  - secure: whether to use HTTPS for interacting with the S3 compatible storage. Default value: false.
  - region: S3 region.
- license: License service settings.
  - type: license type (not version). Copy the numerical value from the values/general.yaml file, which is generated automatically during the fetching of installation artifacts. Do not change this value manually.
  - retryPeriod: duration how often service should try to fetch license from storage if previous attempts were failing.
  - softBlockPeriod: from what period of time the license expiration notification appears. Additional time units d for days and w for weeks are supported.
- ingress: configuration of the Ingress resource. Adapt it to your Ingress installation if needed.
- persistence: configuration of the storage of the License service states.
  - host: endpoint address in the host:port format.
  - secure: whether to use HTTPS for interacting with the S3 compatible storage. Default value: false.
  - region: S3 region.
  - bucket: S3 bucket name.
  - root: S3 bucket root directory to store state files.
  - accessKey: S3 access key to access the S3 bucket.
  - secretKey: S3 secret key to access the S3 bucket.
  Important:
  
  If the specified data is lost, the current license becomes invalid. To get a new license, see the Advanced steps for getting a license.
- tpm: settings to access the Trusted Platform Module (TPM). For license type 2 only (license.type: 2).
  - mountTPMDevice: method of granting access to the TPM:
    - true: mount the TPM into a Kubernetes pod. Privileged access to the main container is enabled.
    - false: use a device plugin to automatically mount TPM inside a Kubernetes pod. You can use the Urbi plugin or build and install a custom plugin in a Kubernetes cluster.
  - pvcBind: create a Persistent Volume Claim (PVC) to link a License service pod to a cluster node.
    - enable: whether to use a PVC. Default value: false.
    - storageClassName: name of a Kubernetes storage class.
- customCAs: custom certificates settings.
  - bundle: text representation of a certificate in the X.509 PEM public-key format.
  - certsPath: bundle mount directory in the container.
- resources: resource usage limits for the cluster. Add this settings block if you use a device plugin to mount TPM.
  - limits.DOMAIN/tpmrm: 1: replace the DOMAIN placeholder with a resource domain name configured in the plugin settings.
- affinity: affinity settings to link License service pods to specific cluster nodes.
  Examples of affinity settings:
  - Place License service pods on different nodes of the cluster (important for all license types, except 1):
```
affinity:
    podAntiAffinity:
        requiredDuringSchedulingIgnoredDuringExecution:
        - topologyKey: kubernetes.io/hostname
            labelSelector:
            matchExpressions:
                - key: app.kubernetes.io/name
                operator: In
                values:
                    - '' # specific value of this parameter depends on your environment settings
```
  - Limit the set of cluster nodes that the License service can access (useful for license type 2):
```
affinity:
    nodeAffinity:
        requiredDuringSchedulingIgnoredDuringExecution:
        nodeSelectorTerms:
            - matchExpressions:
                - key: kubernetes.io/hostname
                operator: In
                values:
                    - node-1 # cluster node name
                    - node-2 # cluster node name
```
  For the detailed descriptions of affinity parameters, see the Kubernetes documentation.
Deploy the service with Helm using the created values-license.yaml configuration file:
```
helm upgrade --install --version=1.32.0 --atomic --values ./values-license.yaml license 2gis-on-premise/license
```
Note:

During the first execution, the command returns an error indicating that the license service pod cannot be launched. This is an expected behavior, proceed with the next steps.

3. Get license

Important

The steps below describe the default way of getting a license. If you need a license after renewing the Kubernetes API server certificate, changing the key or license type or in other corner cases, see the Advanced steps for getting a license.

For license operations service uses DGCLI utility configuration file. For details on the process of obtaining the license, see the utility license mode description.

The process can be launched on one host that has both S3 and internet access or on two separate hosts with different access settings. Take the following steps depending on the selected host configuration.

Using one host with access to S3 and internet

Request a license:

docker run --rm \
-v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
--user $(id -u):$(id -g) \
2gis/dgctl:latest \
license --config=/dgctl-config.yaml

If you are using On-Premise version 1.16.0 or lower, add the --with-license-v1 argument to the end of the command.

Deploy the license service with Helm again:

helm upgrade --install --version=1.32.0 --atomic --values ./values-license.yaml license 2gis-on-premise/license

Using two hosts with different access options

When using two hosts, you need to copy files from and to an S3 compatible storage. For these operations, you can use the DGCLI utility (recommended) or another S3 client.

On both hosts, create a COPY_DIR directory for moving files.
Generate files to request a license on the host with S3 access:
1. Check if all necessary files for requesting a license are ready (if you are using the DGCLI utility):
```
docker run --rm \
-v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
--user $(id -u):$(id -g) \
2gis/dgctl:latest \
license --config=/dgctl-config.yaml --dry-run
```
  If you are using On-Premise version 1.16.0 or lower, add the --with-license-v1 argument to the end of the command.
2. Copy the files for requesting a license from S3 to COPY_DIR:
  - If you are using the DGCLI utility, run the following command:
```
docker run --rm \
-v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
-v $COPY_DIR:/data \
--user $(id -u):$(id -g) \
2gis/dgctl:latest \
save --config=/dgctl-config.yaml --to-dir /data --only-license
```
    If you are using On-Premise version 1.16.0 or lower, add the --with-license-v1 argument to the end of the command.
  - If you use a different S3 client, copy all contents of the license-dir directory from S3 to COPY_DIR.
Copy the COPY_DIR contents from the host with S3 access to the host with internet access.

Request a license on the host with internet access:

Copy the files for requesting a license from COPY_DIR to S3:

docker run --rm \
-v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
-v $COPY_DIR:/data \
--user $(id -u):$(id -g) \
2gis/dgctl:latest \
restore --config=/dgctl-config.yaml --from-dir /data --only-license

If you are using On-Premise version 1.16.0 or lower, add the --with-license-v1 argument to the end of the command.

Send the request:

docker run --rm \
-v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
--user $(id -u):$(id -g) \
2gis/dgctl:latest \
license --config=/dgctl-config.yaml

If you are using On-Premise version 1.16.0 or lower, add the --with-license-v1 argument to the end of the command.

Copy the license file from S3 to COPY_DIR:

docker run --rm \
-v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
-v $COPY_DIR:/data \
--user $(id -u):$(id -g) \
2gis/dgctl:latest \
save --config=/dgctl-config.yaml --to-dir /data --only-license

If you are using On-Premise version 1.16.0 or lower, add the --with-license-v1 argument to the end of the command.

Copy the COPY_DIR contents from the host with internet access to the host with S3 access.
Copy the license file from COPY_DIR to S3:
- If you are using the DGCLI utility, run the following command:
```
docker run --rm \
-v $(pwd)/dgctl-config.yaml:/dgctl-config.yaml \
-v $COPY_DIR:/data \
--user $(id -u):$(id -g) \
2gis/dgctl:latest \
restore --config=/dgctl-config.yaml --from-dir /data --only-license
```
  If you are using On-Premise version 1.16.0 or lower, add the --with-license-v1 argument to the end of the command.
- If you use a different S3 client, copy all contents of the license-dir directory from COPY_DIR to S3.

Deploy the license service with Helm again:

helm upgrade --install --version=1.32.0 --atomic --values ./values-license.yaml license 2gis-on-premise/license

What's next?

Install other On-Premise products:

API Keys service.

Find out how to update the service:

Updating License service