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 Pro 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 dgctl-store 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 http://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.

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

To install License service:

  1. Create configuration file values-license.yaml:

    values-license.yaml
    dgctlDockerRegistry: ''
    
    dgctlStorage:
        host: artifacts.example.com
        secure: false
        bucket: onpremise-artifacts
        accessKey: AKIAIOSFODNN7EXAMPLE
        secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
    
    license:
        type: ''
        updatePeriod: 1h
        retryPeriod: 30s
        softBlockPeriod: 2w
    
    ingress:
        className: nginx
        enabled: true
        hosts:
            host: license.example.com
            paths:
                path: /
                pathType: Prefix
        tls: []
        #- hosts:
        #  - license.example.com
        #  secretName: secret.tls
    
    persistence:
        type: s3
        s3:
            host: artifacts.example.com
            bucket: onpremise-artifacts
            root: 'license_state'
            accessKey: AKIAIOSFODNN7EXAMPLE
            secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
        fs:
            storage: 10Mi
            storageClassName: ''
    
    tpm:
        securityContext: {}
        mountTPMDevice: false
        pvcBind:
            enable: false
            storageClassName: ''
    
    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. 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.
      • updatePeriod: duration how often service should fetch new license from storage. Duration format is any string supported by 'time.ParseDuration'.
      • 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. Depending on the selected storage type, use one of the following settings blocks:

      • type: s3: use an S3-compatible storage (default selection).

        • host: endpoint address in the host:port format.
        • 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.
      • type: fs: use the Kubernetes Persistent Volume.

        • storage: storage size, at least 10Mi.
        • storageClassName: name of the Kubernetes StorageClass.

      Important:

      If the specified data is lost, the current license becomes invalid. To get a new license, contact the On-Premise support service.

    • tmp: 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. If you select this method, add the following settings:

          • securityContext: access control settings of the main container. The settings must provide access to the TPM host (/dev/tpmrm0).

            • privileged: true: enable privileged access to the main container. In this case, License service is launched in the privileged mode.
        • 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.

        • enabled: using a PVC depends on the selected storage type for the License service states:

          • true: for persistence.type: s3.
          • false: for persistence.type: fs (Persistence Volume is already used).
        • storageClassName: name of a Kubernetes storage class. Required only for persistence.type: s3.

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

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:

    dgctl license --version 2
    
  2. Deploy the license service with Helm again:

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

      dgctl license --version 2 --dry-run
      
    2. Copy the files for requesting a license from S3 to COPY_DIR:

      dgctl save --to-dir $COPY_DIR --only-license
      
  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:

      dgctl restore --from-dir $COPY_DIR --only-license
      
    2. Send the request:

      dgctl license --version 2
      
    3. Copy the license file from S3 to COPY_DIR:

      dgctl save --to-dir $COPY_DIR --only-licensе
      
  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:

    dgctl restore --from-dir $COPY_DIR --only-license
    
  7. Deploy the license service with Helm again:

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