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
-
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 docker.storage.example.local:5000
See Fetching installation artifacts Kubernetes secret for accessing Docker Registry onpremise-registry-creds
See Fetching installation artifacts Installation artifacts S3 storage domain name artifacts.example.com
See Fetching installation artifacts Bucket name for installation artifacts onpremise-artifacts
See Fetching installation artifacts Installation artifacts access key AKIAIOSFODNN7EXAMPLE
See Fetching installation artifacts Installation artifacts secret key wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
See Fetching installation artifacts Path to the manifest file manifests/1640661259.json
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.
* 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.
-
Choose the domain names for the services.
Example:
keys.example.com
2. Prepare infrastructure required for the service
Configure PostgreSQL
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 5432
.
Configure the PostgreSQL cluster for usage as a storage:
-
Connect to the cluster a superuser (usually
postgres
). -
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;
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. This instruction assumes that the cluster works on the standard port 3268
.
-
Collect the necessary LDAP settings.
Setting Example value LDAP service username keys_ldap_user
LDAP service password KEYS_LDAP_PaSSw0rd_8901
Base relative distinguished name for performing search in the LDAP catalog dc=2gis
LDAP filter for identifying entries in the search requests (&(objectClass=user)(sAMAccountName=%s))
-
Add a LDAP user named
admin
, which will be granted the admin role in the API Keys service.
3. Install 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.
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 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.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' customCAs: bundle: '' # bundle: | # -----BEGIN CERTIFICATE----- # ... # -----END CERTIFICATE----- certsPath: ''
Where:
-
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 themanifests/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 todgctlStorage.host
via HTTP. Default value:true
.
-
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:Configure:
-
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
ro
section). -
Credentials of the read-write user (the
rw
section).
The Helm chart uses Kubernetes Secrets to store the
password
settings in thero
andrw
sections. -
-
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.baseDN
: base relative distinguished name.filter
: LDAP filter used to identify entries in search requests. For example,(&(objectClass=user)(sAMAccountName=%s))
.
-
-
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 theingress.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.adminUsers
: a list of credentials of administrator users in theusername1: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. -
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.
-
-
Deploy the service with Helm using the created
values-keys.yaml
configuration file:helm upgrade --install --version=1.28.2 --atomic --wait-for-jobs --values ./values-keys.yaml keys 2gis-on-premise/keys
-
Add the administrator users to the deployed service via the
keysctl
utility. These users will be assigned the API Keys service administrator role.Important note:
When using LDAP, it is sufficient to add a single user. When using credentials list (the
api.adminUsers
setting), add all the users form the list.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:
-
Open the admin web interface in a browser (use the value of the
admin.host
setting from thevalues-keys.yaml
file):https://keys.example.com/
-
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?
-
Find out how to update the service:
-
Install other On-Premise products:
-
Find out how to generate API keys: