Installing API Keys service
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.
Consider getting familiar with:
Make sure the necessary preparation steps are completed:
Collect the necessary information that was set or retrieved on previous steps:
Object Example value How to get value Docker Registry mirror endpoint
See Fetching installation artifacts Kubernetes secret for accessing Docker Registry
See Fetching installation artifacts Installation artifacts S3 storage domain name
See Fetching installation artifacts Bucket name for installation artifacts
See Fetching installation artifacts Installation artifacts access key
See Fetching installation artifacts Installation artifacts secret key
See Fetching installation artifacts Path to the manifest file
See Fetching installation artifacts
* These storage requirements may vary depending on the configured statistics storage time period. The greater this period is, the more storage space is required.
Choose the domain names for the services.
Place a PostgreSQL cluster with the domain name
keys-postgresql.storage.example.local in the private network. This instruction assumes that the cluster works on the standard port
Configure the PostgreSQL cluster for usage as a storage:
Connect to the cluster a superuser (usually
Create two database users that will be used for the service. 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';
Create a database owned by one of the users.
create database onpremise_keys owner keys_superuser_rw;
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;
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. This instruction assumes that the cluster works on the standard port
Collect the necessary LDAP settings.
Setting Example value LDAP service username
LDAP service password
Base relative distinguished name for performing search in the LDAP catalog
LDAP filter for identifying entries in the search requests
Add a LDAP user named
admin, which will be granted the admin role in the API Keys 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.
dgctlDockerRegistry: docker.storage.example.local:5000 dgctlStorage: host: artifacts.storage.example.local:443 bucket: keys accessKey: AKIAIOSFODNN7EXAMPLE secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY manifest: manifests/1640661259.json postgres: ro: host: keys-postgresql.storage.example.local port: 5432 name: onpremise_keys username: keys_superuser_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.example.com ingress: enabled: true className: nginx hosts: - host: keys.example.com paths: - path: / pathType: Prefix tls:  #- hosts: # - keys.example.com # secretName: secret.tls api: adminUsers: 'admin:8k7RVCP8m3AABDzD'
dgctlDockerRegistry: your Docker Registry endpoint where On-Premise services' images reside.
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.jsonformat. This file contains the description of pieces of data that the service requires to operate. See Installation artifacts lifecycle.
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: hostname or IP address of the server.
port: listening port of the server.
name: database name.
Credentials of the read-only user (the
Credentials of the read-write user (the
The Helm chart uses Kubernetes Secrets to store the
passwordsettings in the
ldap: access settings for the LDAP server.
host: hostname 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 service. See the minimal requirements table for the actual information about recommended values.
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.hostparameter should be accessible from the outside of your Kubernetes cluster, so that users in the private network can browse the URL.
api.adminUsers: a list of credentials of administrator users in the
The Helm chart uses Kubernetes Secrets to store the setting.
If you have a LDAP server, it is recommended to use it for the authentication and skip the
Deploy the service with Helm using the created
helm upgrade --install --version=1.14.0 --atomic --wait-for-jobs --values ./values-keys.yaml keys 2gis-on-premise/keys
Add the administrator users to the deployed service via the
keysctlutility. These users will be assigned the API Keys service administrator role.
When using LDAP, it is sufficient to add a single user. When using credentials list (the
api.adminUserssetting), add all the users form the list.
To add a user, execute the following command from the inside of any
keysctl users add admin 'Keys Service Admin'
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
To test the operability of the API Keys service, do the following:
Open the admin web interface in a browser (use the value of the
admin.hostsetting from the
Log in using the administrator user credentials (the one that was granted administrator role via the
keysctlutility). You should see the API Keys service web interface for managing API keys.