Skip to main content

Installing API Keys service

Important note:

All passwords and keys in this section are given for illustration purposes.

During a real installation, it is recommended to use more complex and reliable passwords.

1. Before installing​

  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:

    ObjectExample valueHow to get value
    Docker Registry mirror endpointdocker.storage.example.local:5000See Fetching installation artifacts
    Kubernetes secret for accessing Docker Registryonpremise-registry-credsSee Fetching installation artifacts
    Installation artifacts S3 storage domain nameartifacts.example.comSee Fetching installation artifacts
    Bucket name for installation artifactsonpremise-artifactsSee Fetching installation artifacts
    Installation artifacts access keyAKIAIOSFODNN7EXAMPLESee Fetching installation artifacts
    Installation artifacts secret keywJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEYSee Fetching installation artifacts
    Path to the manifest filemanifests/1640661259.jsonSee 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.

    * These storage requirements may vary depending on the configured statistics storage time period. The greater this period is, the more storage space is required.

    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.

  5. Choose the domain names for the services.

    Example:

    • Administrator web interface: keys-admin.example.com
    • API backend: keys-api.example.com

2. Prepare infrastructure​

Configure PostgreSQL​

Place a PostgreSQL cluster with the domain name keys-postgresql.storage.example.local in the private network. It is assumed that the cluster works on the standard port 5432.

Configure the PostgreSQL cluster for usage as a storage:

  1. Connect to the cluster as a superuser (usually postgres).

  2. Create two database users and set passwords for the users:

    create user keys_superuser_rw password 'KEYS_Db_Owner_Password_1234';
    create user keys_user_ro password 'KEYS_Db_RO_User_Password_5678';

  3. Create a database owned by one of the users:

    create database onpremise_keys owner keys_superuser_rw;

  4. Grant limited permissions to the database for the other user:

    \c onpremise_keys

    ALTER DEFAULT PRIVILEGES FOR ROLE keys_superuser_rw IN SCHEMA public GRANT SELECT ON TABLES TO keys_user_ro;
    ALTER DEFAULT PRIVILEGES FOR ROLE keys_superuser_rw IN SCHEMA public GRANT SELECT ON SEQUENCES TO keys_user_ro;

Configure LDAP​

For the servers to be able to authenticate API Keys service administrators, it is recommended to use a LDAP server (e.g., Microsoft Active Directory). This step can be skipped if you cannot deploy a LDAP server and are going to use authentication based on plaintext password in the configuration file.

Place a LDAP server with the domain name keys-ldap.storage.example.local in the private network. It is assumed that the cluster works on the standard port 3268.

  1. Collect the necessary LDAP settings.

    SettingExample value
    LDAP service usernamekeys_ldap_user
    LDAP service passwordKEYS_LDAP_PaSSw0rd_8901
    Base relative distinguished name for performing search in the LDAP catalogdc=2gis
    LDAP filter for identifying entries in the search requests(&(objectClass=user)(sAMAccountName=%s))

  2. Add a LDAP user named admin, which will be granted the admin role in the API Keys service.

Configure Redis​

  1. Place Redis in the private network.

  2. Create a user and set a password:

    Example:

    • Username: redisuser
    • Password: Redis_Password_6379

3. Install API Keys 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-keys.yaml
    dgctlDockerRegistry: docker.storage.example.local:5000

    dgctlStorage:
        host: artifacts.storage.example.local:443
        bucket: onpremise-artifacts
        accessKey: AKIAIOSFODNN7EXAMPLE
        secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
        manifest: manifests/1640661259.json
        secure: false
        region: ''
        verifySsl: true

    redis:
        host: redis.cache.example.local
        port: 6379
        db: 1
        password: Redis_Password_6379

    postgres:
        ro:
            host: keys-postgresql.storage.example.local
            port: '5432'
            name: onpremise_keys
            username: keys_user_ro
            password: KEYS_Db_RO_User_Password_5678
        rw:
            host: keys-postgresql.storage.example.local
            port: '5432'
            name: onpremise_keys
            username: keys_superuser_rw
            password: KEYS_Db_Owner_Password_1234

    ldap:
        host: ldap.keys.example.com
        port: 3268

        useStartTLS: false
        useLDAPS: false
        skipServerCertificateVerify: false
        serverName: ldap.keys.example.com
        clientCertificatePath: /home/user/certificates/cert.crt
        clientKeyPath: /home/user/certificates/cert.key
        rootCertificateAuthoritiesPath: /home/user/certificates/root.cer

        bind:
            dn: keys_ldap_user
            password: KEYS_LDAP_PaSSw0rd_8901

        search:
            baseDN: dc=2gis
            filter: (&(objectClass=user)(sAMAccountName=%s))

    tasker:
        resources:
            requests:
                cpu: 10m
                memory: 32Mi
            limits:
                cpu: 100m
                memory: 64Mi

        delay: 30s

    admin:
        host: https://keys-admin.example.com

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

    api:
        adminUsers: 'admin:8k7RVCP8m3AABDzD'

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

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

    Where:

    • dgctlDockerRegistry: endpoint of your Docker Registry with the images of the On-Premise services.

    • dgctlStorage: Installation Artifacts Storage settings.

      • Fill in the common settings to access the storage: endpoint, bucket, and access credentials.
      • manifest: fill in the path to the manifest file in the manifests/1640661259.json format. This file contains the description of pieces of data that the service requires to operate. See Installation artifacts lifecycle.
      • secure: whether to use HTTPS for interacting with the S3 compatible storage. Default value: false.
      • region: S3 storage region.
      • verifySsl: whether to enable validation of SSL certificates when connecting to dgctlStorage.host via HTTP. Default value: true.

    • redis: access settings for the Regis server:

      • host: host name or IP address of the server.
      • port: listening port of the server.
      • db: Redis database number.
      • password: Redis user password. If no authentication is required, leave the field empty.

    • postgres: access settings for the PostgreSQL server.

      The API Keys service serves the data in two modes: read-only (ro) and read-write (rw). The service uses a single database for each mode, however, users are configured with different set of permissions (see the step 1 for details). Set the settings in these sections as follows:

      • Settings that are common for both modes:

        • host: host name or IP address of the server. You can specify multiple host names or IP addresses separated by comma.
        • port: listening port of the server. You can specify multiple ports separated by comma.
        • name: database name.

      • Credentials of the read-only user (the ro section).

      • Credentials of the read-write user (the rw section).

      The Helm chart uses Kubernetes Secrets to store the password settings in the ro and rw sections.

    • ldap: access settings for the LDAP server.

      • host: host name or IP address of the server.

      • port: listening port of the server.

      • A group of setting to configure secure access to the LDAP server:

        • useStartTLS: use StartTLS.
        • useLDAPS: use Secure LDAP.
        • skipServerCertificateVerify: do not verify the server certificate.
        • serverName: string with the server name. Used when verifying the server certificate.
        • clientCertificatePath: path to client certificate.
        • clientKeyPath: path to client key.
        • rootCertificateAuthoritiesPath: path to the root certificate authorities file.

      • bind: credentials for accessing the LDAP server.

        • dn: distinguished user name.
        • password: user password.

      • search: LDAP search settings.

    • tasker: settings of the Tasker service, which do administrative actions on API keys.

      • resources: computational resources settings for the service. To find out recommended resource values, see Computational resources.
      • delay: time interval (in seconds). This setting defines the interval of checking tasks that are related to delayed action items (for example, blocking an API key).

    • admin: settings of the API keys admin web service (Web UI).

      • host: URL of the API keys frontend. This URL should be accessible from the outside of your Kubernetes cluster, so that users in the private network can browse the URL.

      • ingress: configuration of the Ingress resource. Adapt it to your Ingress installation. The URL specified in the ingress.hosts.host parameter should be accessible from the outside of your Kubernetes cluster, so that users in the private network can browse the URL.

    • api: settings of the API service.

      • adminUsers: a list of credentials of administrator users in the username1:password1,username2:password2,... format.

        The Helm chart uses Kubernetes Secrets to store the setting.

        Note:

        If you have a LDAP server, it is recommended to use it for the authentication and skip the api.adminUsers setting.

      • ingress: configuration of the Ingress resource. Adapt it to your Ingress installation. The URL specified in the ingress.hosts.host parameter should be accessible from the outside of your Kubernetes cluster, so that users in the private network can browse the URL.

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

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

    helm upgrade --install --version=1.32.0 --atomic --wait-for-jobs --values ./values-keys.yaml keys 2gis-on-premise/keys

  3. Add the administrator users to the deployed service via the keysctl utility. These users will be assigned the API Keys service administrator role.

    To add a user, execute the following command from the inside of any keys-api pod:

    keysctl users add admin 'Keys Service Admin'

4. Fetch the service tokens​

Each On-Premise service that integrates with the API Keys service is forced to share information about the end user's API key usage with the API keys backend by design. To communicate with the backend, the service needs the service token to be configured during the deployment.

To get a list of the service keys to be used with a certain On-Premise API Keys service deployment, execute the following command from the inside of any keys-api pod:

keysctl services

4. Test deployment​

To test the operability of the API Keys service, do the following:

  1. Open the admin web interface in a browser (use the value of the admin.host setting from the values-keys.yaml file):

    https://keys-admin.example.com

  2. Log in using the administrator user credentials (the one that was granted administrator role via the keysctl utility). You should see the API Keys service web interface for managing API keys.

What's next?​