Installing search API
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 License service endpoint http://license
See Installing License service API Keys service endpoint http://keys-api
See Installing API Keys service Service token CATALOG_APIS_TOKEN
See Installing API Keys service -
Make sure that the resource requirements specified in the Helm charts are met:
For more information on how to do this, refer to the System requirements document.
Note
Contents of Helm charts described in this chapter are relevant for the latest On-Premise version (see Release notes). To find parameters for earlier versions, open the required values.yaml on GitHub and enter the required version number (for example, 1.18.0) in the tag switcher on the left.
-
Choose domain names for the services.
Example:
- Domain name for Search API:
search-api.example.com
- Domain name for Catalog APIs:
catalog-api.example.com
- Domain name for Search API:
2. Prepare infrastructure required for the service
Configure PostgreSQL
Place a PostgreSQL cluster with the domain name catalog-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 a database user that will be used for the service. Set a password for the user.
create user dbuser_catalog password '650D7AmZjSR1dkNa';
-
Create a database owned by this user.
create database onpremise_catalog owner dbuser_catalog;
-
Install necessary database extensions:
\c onpremise_catalog create schema extensions; grant usage on schema extensions to public; grant execute on all functions in schema extensions to public; alter default privileges in schema extensions grant execute on functions to public; alter default privileges in schema extensions grant usage on types to public; create extension if not exists plpgsql with schema pg_catalog; create extension if not exists jsquery with schema extensions; create extension if not exists postgis with schema extensions;
3. Install search API services
Install Search API 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-search.yaml
dgctlDockerRegistry: docker.storage.example.local:5000 imagePullSecrets: - name: onpremise-registry-creds imagePullPolicy: IfNotPresent dgctlStorage: host: artifacts.storage.example.local:443 bucket: onpremise-artifacts accessKey: AKIAIOSFODNN7EXAMPLE secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY manifest: manifests/1640661259.json secure: false region: '' api: resources: limits: cpu: 1 memory: 3G requests: cpu: 100m memory: 1G nginx: resources: limits: cpu: 1 memory: 1G requests: cpu: 100m memory: 200Mi ingress: enabled: true className: nginx hosts: - host: search-api.example.com paths: - path: / pathType: Prefix tls: [] #- hosts: # - search-api.example.com # secretName: secret.tls 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.
-
api.resources
: computational resources settings for the API backend service. To find out recommended resource values, see Computational resources. -
nginx.resources
: computational resources settings for the NGINX backend service. To find out recommended resource values, see Computational resources. -
ingress
: configuration of the Ingress resource. Adapt it to your Ingress installation. This URL 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.
-
-
Deploy the service with Helm using the created
values-search.yaml
configuration file.helm upgrade --install --version=1.29.0 --atomic --values ./values-search.yaml search-api 2gis-on-premise/search-api
Install Catalog APIs service
-
Create a Helm configuration file. See here for more details on the available settings.
Note:
You can configure the process of importing new data for Catalog APIs. Use the
importer
settings group of the configuration file (see below).The example is prefilled with the necessary data collected on previous steps.
values-catalog.yaml
dgctlDockerRegistry: docker.storage.example.local:5000 imagePullSecrets: - name: onpremise-registry-creds imagePullPolicy: IfNotPresent dgctlStorage: host: artifacts.storage.example.local:443 bucket: onpremise-artifacts accessKey: AKIAIOSFODNN7EXAMPLE secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY manifest: manifests/1640661259.json secure: false region: '' verifySsl: true api: postgres: host: catalog-postgresql.storage.example.local port: 5432 name: onpremise_catalog username: dbuser_catalog password: 650D7AmZjSR1dkNa ingress: enabled: true className: nginx hosts: - host: catalog-api.example.com paths: - path: / pathType: Prefix tls: [] #- hosts: # - catalog-api.example.com # secretName: secret.tls search: url: http://search-api keys: url: http://keys-api token: CATALOG_APIS_TOKEN importer: postgres: host: catalog-postgresql.storage.example.local port: 5432 name: onpremise_catalog username: dbuser_catalog password: 650D7AmZjSR1dkNa schemaSwitchEnabled: true cleaner: enabled: true versionLimit: 2 license: url: 'https://license' requestTimeout: 1s customCAs: bundle: '' # bundle: | # -----BEGIN CERTIFICATE----- # ... # -----END CERTIFICATE----- certsPath: ''
Where:
-
dgctlDockerRegistry
: your Docker Registry endpoint where images of On-Premise services 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
.
-
api.postgres
: the PostgreSQL database access settings. Use the values you configured in the PostgreSQL on the previous step.host
: host name of the serverport
: port of the servername
: database nameusername
: user namepassword
: user password
-
api.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. -
search
: the Search API service access settings.url
: URL of the service. This URL must be accessible from all the pods within your Kubernetes cluster.
-
keys
: the API Keys service settings.url
: URL of the service. This URL must be accessible from all the pods within your Kubernetes cluster.token
: service token for sharing usage statistics with the API Keys service (see Installing API Keys service).
-
importer
: settings of the data import (Kubernetes Importer job). New data sets are imported only if no imports have been done for the given manifest before.-
postgres
: settings of the PostgreSQL server access to import new data for objects.host
: host name of the serverport
: port of the servername
: database nameusername
: user namepassword
: user passwordschemaSwitchEnabled
: enable/disable working with schemas.true
: data is imported to a new schema every time. Switching to older schemas and cleaning them is available.false
: creation of new schemas and cleaning the data base is done manually by the administrator.
For details, see the Update Catalog APIs service section.
-
cleaner
: settings of automatically removing old data sets.enabled
: automatic removal of old data sets is enabled. For details, see the Update Catalog APIs service section.versionLimit
: number of old data sets to keep.
For additional information about the import process, see Installation artifacts lifecycle.
-
-
license
: the License service settings.url
: License service URL address. Example:https://license
.requestTimeout
: timeout for requests to the License service.
-
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-catalog.yaml
configuration file.helm upgrade --install --version=1.29.0 --atomic --values ./values-catalog.yaml catalog-api 2gis-on-premise/catalog-api
If the configuration file contains
importer
settings, the command checks if the data already exists in the database and if needed, imports it into PostgreSQL. After that, Helm installs the service.
4. Test deployment
Test Search API service
To test that the Search API service is working, you can make a GET request to the status
endpoint:
curl search-api.example.com/v2/status?f=common
Test Catalog APIs service
To test that the Catalog APIs service is working, you can do the following:
-
Using API Keys Admin, create an API key that has access to Places API and Regions API.
-
Make the following GET request, replacing:
API_KEY
with the created key.City
with any city name you want to search the information for.
curl catalog-api.example.com/3.0/items/geocode?key=API_KEY&q=City
This request will test the operability of Catalog APIs, Search API, and the PostgreSQL database.
What's next?
-
Read documentation for search API:
-
Find out how to update the services:
-
Install other On-Premise products: