.. _configuration:

Configuration
==============

The ``ska-db-oda`` chart creates a ``Job`` that runs DDL scripts against a Postgres instance and also deploys
the ``ska-db-oda`` application that connects to Postgres in a similar way, as described below.

The ``ska-db-oda-umbrella`` chart deploys a Postgres instance using the ``PGDBInstance`` operator and
is configurable as described below. The ``Job`` that runs from the main chart will then add the tables to the database.

As OSO deploys several applications that connect to Postgres, we make use of global Helm values to minimise
duplication. The provisioning of the database also then can make use of these for testing environments.

Postgres Instance
-------------------
The following Helm values are used to configure the Postgres instance. Rather than letting the operator create a
password, the umbrella chart also defines a Secret that is pulled from Vault.

.. code-block:: yaml

    global:
      oda:
        postgres:
          cluster: pgstfc # The name of the SGCluster
          clusterNamespace: ska-tango-archiver-db # The namespace the SGCluster is deployed to
          database: oda # This needs to be unique for each pipeline run so is overwritten in the makefile
          user: ~ # If this is left as null, the user will be the database name appended with `_admin`
          secret:
            existingSecret:
              # This is the resource name of a k8s Secret that has a PGPASSWORD key to be used to
              # as the provisioned database user's password
              # If it is left as null a new secret will be created, pulling the value from Vault
              name: ~
            vault:
              enabled: true
              mount: dev
              secretPath: "team-buttons/ska-db-oda/credentials"
              secretKeys:
                - "PGPASSWORD"

For more details on this, see the documentation on the ``PGDBInstance`` CRD provided by Services.

``ska-db-oda`` application
----------------------------

The following environment variables are used to configure the application. They are set via a Kubernetes ConfigMap
with values coming from the Helm values.yaml.

Generally, if an variable default can be set in the application it will be. Some 'defaults' are more dynamic
and need release or namespace info. In this case a sensible default has been set in the charts but can be overridden via
a Helm value at deploy time.

.. list-table:: Environment variables used by ska-db-oda
   :widths: 10 10 10 10 10
   :header-rows: 1

   * - Environment variable
     - Description
     - Required/optional in the application
     - Corresponding Helm value
     - Required/optional in the Helm chart
   * - SKUID_URL
     - The Kubernetes service address of a running SKUID service
     - Required
     - ``ska-db-oda.rest.skuid.url``
     - Optional - will fall back on: ``ska-ser-skuid-{{ .Release.Name }}-svc.{{ .Release.Namespace }}.svc.{{ .Values.global.cluster_domain }}:9870``
   * - PGHOST
     - The address of the PostgreSQL instance that the postgres ODA will connect to.
     - Required
     - ``global.oda.postgres.host``
     - Optional - will fall back on: ``{{.Values.postgres.cluster}}.{{.Values.postgres.clusterNamespace}}.svc.{{ .Values.global.cluster_domain }}``
   * - PGUSER
     - The admin user of the PostgreSQL instance that the postgres ODA will connect to.
     - Optional - default: ``oda_admin``
     - ``global.oda.postgres.user``
     - Optional - no default in chart
   * - PGPASSWORD
     - The admin password of the PostgreSQL instance that the postgres ODA will connect to.
     - Required
     - Pulled from Vault - see :doc:`secret_management`
     -
   * - PGPORT
     - The port of the PostgreSQL instance that the postgres ODA will connect to.
     - Optional - default: ``5432``
     - ``global.oda.postgres.port``
     - Optional - no default in chart
   * - PGDATABASE
     - The name of the database within a PostgreSQL instance that the postgres ODA will connect to.
     - Optional - default: ``oda``
     - ``global.oda.postgres.database``
     - Optional - no default in chart (overwritten in the Makefile)

Connecting to an externally managed Postgres
----------------------------------------------

The chart is configured so that Postgres connection details can be set as Helm values as described above, and the Helm values
are diplayed below for completeness.

Note there is a ``existingSecret`` option that might be more useful depending on the environment.

.. code-block:: yaml

    global:
      minikube: true
      cluster_domain: techops.internal.skao.int # For this project's pipelines, this is overwritten with the value of the CLUSTER_DOMAIN variable
      oda:
        # These global values are used by the ska-db-oda rest server deployment to connect to the postgres instance
        # See RtD for more details.
        postgres:
          # If this is not set, PGHOST will default to the address of the Postgres instance deployed by the Stackgres operator,
          # using the .Values.global.oda.postgres.cluster and .Values.global.oda.postgres.clusterNamespace values
          host: ~
          port: "5432"
          database: ~ # For pipeline deployments, this is dynamic so is set in the Makefile
          user: ~ # For pipeline deployments, this is set in the makefile to <database>_admin
          secret:
            existingSecret:
              # This is the resource name of a k8s Secret and that has a PGPASSWORD key
              # If it is left as null a new secret will be created, pulling the value from Vault
              # Note: if this Secret also contains the other PG_ environment variables then they will override the values
              # in the ConfigMap. This is useful is the Postgres deployment is managed elsewhere and there is already
              # a Secret in the cluster with all the connection details.
              name: ~
            vault:
              enabled: true
              mount: dev
              secretPath: "team-buttons/ska-db-oda/credentials"
              secretKeys:
                - "PGPASSWORD"