Skip to content

Latest commit

 

History

History
183 lines (146 loc) · 5.91 KB

external-databases.md

File metadata and controls

183 lines (146 loc) · 5.91 KB

Using external databases

The included postgres database is in support of the kick-the-tyres user and should just work.

For all other users we recommend configuring your deployment with an external database.

You can use an external database for the CF API and UAA by providing following values:

#@data/values
---
capi:
  #@overlay/replace
  database:
    adapter: postgres
    host: <host>
    port: <port>
    user: <user>
    password: <password>
    name: <database>
    ca_cert: <ca certificate for tls>

uaa:
  #@overlay/replace
  database:
    adapter: postgresql
    host: <host>
    port: <port>
    user: <user>
    password: <password>
    name: <database>
    ca_cert: <ca certificate for tls>

Please note to the different spelling of postgres and postgresql for capi and uaa.

Limitations

Providing a ca_cert enables SSL full verification. SQL database services that do not have a hostname and certificate valid for that hostname (e.g. GCP Cloud SQL) will not be able to negotiate a connection in this mode. Skipping hostname validation is not supported.

Setup

As prerequisite, you need to execute the following steps to configure your postgres installation for cf-for-k8s:

  1. Set the environment variables

    export PGPASSWORD=<password of postgres super user>
export PGHOST=<host where postres is running>
export DB_VALUES_FILE=db-values.yml

  2. Run the following script. It will

    • create one database each for CF API and UAA
    • create one user each for CF API and UAA
    • activate the citext extension for each of these databases

    The following uses the python module yq.

    CCDB_USERNAME=$(yq -r '.capi.database.user' "$DB_VALUES_FILE")
CCDB_PASSWORD=$(yq -r '.capi.database.password' "$DB_VALUES_FILE")
CCDB_NAME=$(yq -r '.capi.database.name' "$DB_VALUES_FILE")
UAADB_USERNAME=$(yq -r '.uaa.database.user' "$DB_VALUES_FILE")
UAADB_PASSWORD=$(yq -r '.uaa.database.password' "$DB_VALUES_FILE")
UAADB_NAME=$(yq -r '.uaa.database.name' "$DB_VALUES_FILE")
cat > "$TMPDIR/setup_db.sql" <<EOT
CREATE DATABASE ${CCDB_NAME};
CREATE ROLE ${CCDB_USERNAME} LOGIN PASSWORD '${CCDB_PASSWORD}';
CREATE DATABASE ${UAADB_NAME};
CREATE ROLE ${UAADB_USERNAME} LOGIN PASSWORD '${UAADB_PASSWORD}';
EOT
psql -U postgres -f "$TMPDIR/setup_db.sql"
psql -U postgres -d "${CCDB_NAME}" -c "CREATE EXTENSION citext"
psql -U postgres -d "${UAADB_NAME}" -c "CREATE EXTENSION citext"

    To use the Golang yq utility, use these assignments.

    CCDB_USERNAME=$(yq read "$DB_VALUES_FILE" 'capi.database.user')
CCDB_PASSWORD=$(yq read "$DB_VALUES_FILE" 'capi.database.password')
CCDB_NAME=$(yq read "$DB_VALUES_FILE" 'capi.database.name')
UAADB_USERNAME=$(yq read "$DB_VALUES_FILE" 'uaa.database.user')
UAADB_PASSWORD=$(yq read "$DB_VALUES_FILE" 'uaa.database.password')
UAADB_NAME=$(yq read "$DB_VALUES_FILE" 'uaa.database.name')
...

Installation of an internal database

If both CF API and UAA, are configured to use an external database, no internal database will be deployed.

Example with external RDS database

In the following section, we will show how to setup an AWS RDS database and configure it as the datebase to be used for CF API and UAA. Please note that the values passed for RDS creation are not suitable for production environments.

  1. Create a RDS database. The following command will create a small database for development. Please adjust the settings to your requirements.

    export PGPASSWORD=<your password>
aws rds create-db-instance \
    --engine postgres \
    --db-instance-identifier cf-for-k8s \
    --allocated-storage 20 \
    --db-instance-class db.t2.micro \
    --db-subnet-group default \
    --master-username postgres \
    --master-user-password "$PGPASSWORD" \
    --backup-retention-period 7 \
    --publicly-accessible

  2. Wait until RDS database is ready

    aws rds wait db-instance-available --db-instance-identifier cf-for-k8s

  3. Extract database hostname

    aws rds describe-db-instances --db-instance-identifier cf-for-k8s | jq -r '.DBInstances[0].Endpoint.Address'

  4. Create configuration file "$DB_VALUES_FILE". Please replace the host, password and ca_cert in this file accordingly. You can download the certificate from here

    #@data/values
---
capi:
  #@override/replace
  database:
    adapter: postgres
    host: cf-for-k8s.c4pknugnyzdd.eu-central-1.rds.amazonaws.com
    port: 5432
    user: capi_user
    password: <password for capi_user>
    name: capi_db
    ca_cert: |
      -----BEGIN CERTIFICATE-----
      ...

uaa:
  #@overlay/replace
  database:
    adapter: postgresql
    host: cf-for-k8s.c4pknugnyzdd.eu-central-1.rds.amazonaws.com
    port: 5432
    user: uaa_user
    password: <password for uaa_user>
    name: uaa_db
    ca_cert: |
      -----BEGIN CERTIFICATE-----
      ...

  5. Set environment variables

    export DB_VALUES_FILE=db-values.yml
export PGHOST=$(cat "$DB_VALUES_FILE" | yq -r '.capi.database.host' )

  6. Run configuration script from above

    CCDB_USERNAME=...
...

  7. Install cf-for-k8s

    i. Configure your cf-values.yml file i. Render the final K8s template to raw K8s yaml. Pass the "$DB_VALUES_FILE" file as additional file to ytt

    ytt -f config -f "$TMPDIR/cf-values.yml" -f "$DB_VALUES_FILE" > "$TMPDIR/cf-for-k8s-rendered.yml"

    ii. Install using kapp

    kapp deploy -a cf-for-k8s -f "$TMPDIR/cf-for-k8s-rendered.yml"