License service | On-Premise | 2GIS Documentation

Installing License service

  1. Consider getting familiar with:

  2. Make sure the necessary preparation steps are completed:

    1. Preparation for installation
    2. Fetching installation artifacts
  3. 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
  4. 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.

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

To install License service:

  1. 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
        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
        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.
    • 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.
      • 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.

  2. Deploy the service with Helm using the created values-license.yaml configuration file:

    helm upgrade --install --version=1.24.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.

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.

The process of obtaining a license includes sending requests to an S3-compatible storage and using the internet.

  1. License service generates files to request a license and stores them in an S3-compatible storage.
  2. 2GIS CLI utility reads these files from S3, builds a request with them, and sends it via the internet.
  3. When the request is handled, a license is returned. The 2GIS CLI utility writes it to the S3-compatible storage.
  4. License service reads the license file and updates the state.

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.

For license operations service uses DGCLI utility configuration file. All parameters are described in DGCLI Configuration File.

  1. 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.

  2. Deploy the license service with Helm again:

    helm upgrade --install --version=1.24.0 --atomic --values ./values-license.yaml license 2gis-on-premise/license
    
  1. On both hosts, create a COPY_DIR directory for moving files.

  2. Generate files to request a license on the host with S3 access:

    1. Check if all necessary files for requesting a license are ready:

      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:

      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.

  3. Copy the COPY_DIR contents from the host with S3 access to the host with internet access.

  4. Request a license on the host with internet access:

    1. 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.

    2. 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.

    3. 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.

  5. Copy the COPY_DIR contents from the host with internet access to the host with S3 access.

  6. Copy the license file 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.

  7. Deploy the license service with Helm again:

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

What's next?

Install other On-Premise products:

Find out how to update the service: