configuring-external-services.adoc

contentTags
platform Server v4.4 Server Admin

Configuring external services

This page describes how to configure external services for use with either a new CircleCI server v4.4 installation or migrating internal PostgreSQL and MongoDB data from existing CircleCI server v4.4 installation to your externalized datastores.

PostgreSQL

Best practices for PostgreSQL

Note	Your externalized PostgreSQL instance needs to be version 12.1 or higher.

Consider running at least two PostgreSQL replicas to allow recovery from primary failure and for backups. The table below shows the recommended specifications for PostgreSQL machines:

# of Daily Active Users	# of PostgreSQL Replicas	CPU	RAM	Disk	NIC Speed
<50	2	8 Cores	16 GB	100 GB	1 Gbps
50 - 250	2	8 Cores	16 GB	200 GB	1 Gbps
250 - 1000	3	8 Cores	32 GB	500 GB	10 Gbps
1000 - 5000	3	8 Cores	32 GB	1 TB	10 Gbps
5000+	3	8 Cores	32 GB	1 TB	10 Gbps

Migrating from an internal PostgreSQL to an externalized source

{% include snippets/server/migrate-internal-postgres-to-external.adoc %}

Connecting your external PostgreSQL instance to CircleCI server

Once you have set up your external PostgreSQL instance, add the following to your values.yaml file so that your CircleCI server instance can access it.

postgresql:
  internal: false
  postgresqlHost: <domain> # The domain or IP address of your PostgreSQL instance
  postgresqlPort: <port> # The port of your PostgreSQL instance

Note	postgresql.internal: false will remove any previously deployed PostgreSQL instance deployed internally

Create the secret and then add the following values to values.yaml:

kubectl create secret generic postgresql \
  --from-literal=postgres-password=<postgres-password>

postgresql:
  ...
  auth:
    username: <username>
    existingSecret: postgresql

Add the following to the values.yaml file. CircleCI will create the secret automatically:

postgresql:
  ...
  auth:
    username: <username> # A user with the appropriate privileges to access your PostgreSQL instance.
    password: <password> # The password of the user account used to access your PostgreSQL instance.

The changes will take effect upon running helm install/upgrade. If you are completing a migration to an externalized PostgreSQL instance then when you perform helm upgrade, the scaled down pods will be scaled back to their replica numbers as defined by your values.yaml.

Back up PostgreSQL

PostgreSQL provides official documentation for backing up and restoring your PostgreSQL 12 install, which can be found here.

We strongly recommend the following:

• Take daily backups

• Keep at least 30 days of backups

• Use encrypted storage for backups as databases might contain sensitive information

• Perform a backup before each upgrade of CircleCI server

MongoDB

Note	If using your own MongoDB instance, it needs to be version 3.6 or higher.

Migrating from an internal MongoDB to an externalized source

{% include snippets/server/migrate-internal-mongo-to-external.adoc %}

Connecting your external MongoDB instance to CircleCI server

Once you have configured your external MongoDB instance, add the following to your values.yaml file to connect your CircleCI server instance.

mongodb:
  internal: false
  hosts: <hostname:port> # this can be a comma-separated list of multiple hosts for sharded instances
  ssl: <ssl-enabled>
  # If using an SSL connection with custom CA or self-signed certs, set this
  # to true
  tlsInsecure: false
  # Any other options you'd like to append to the MongoDB connection string.
  # Format as query string (key=value pairs, separated by &, special characters
  # need to be URL encoded)
  options: <additional-options>
  auth:
    database: <authentication-source-database
    mechanism: SCRAM-SHA-1

Create the secret and then add the following values to values.yaml:

kubectl create secret generic mongodb \
--from-literal=mongodb-root-password=<root-password> \
--from-literal=mongodb-password=dontmatter

mongodb:
  ...
  auth:
    ...
    username: <username>
    existingSecret: mongodb

Add the following to the values.yaml file. CircleCI will create the secret automatically:

mongodb:
  ...
  auth:
    ...
    username: <username>
    rootPassword: <root-password>
    password: <password>

The changes will take effect upon running helm install/upgrade. If you are completing a migration to an externalized MongoDB instance then when you perform helm upgrade, the scaled down pods will be scaled back to their replica numbers as defined by your values.yaml.