|
| 1 | +:_content-type: PROCEDURE |
| 2 | +[id="configuring-cert-based-auth-quay-sql"] |
| 3 | += Configuring certificate-based authentication with SQL |
| 4 | + |
| 5 | +The following procedure demonstrates how to connect {productname} with an SQL database using secure client-side certificates. This method ensures both connectivity and authentication through Certificate Trust Verification, as it verifies the SQL server's certificate against a trusted Certificate Authority (CA). This enhances the security of the connection between {productname} and your SQL server while simplifying automation for your deployment. Although the example uses Google Cloud Platform's CloudSQL, the procedure also applies to PostgreSQL and other supported databases. |
| 6 | + |
| 7 | +.Prerequisites |
| 8 | + |
| 9 | +* You have generated custom Certificate Authorities (CAs) and your SSL/TLS certificates and keys are available in `PEM` format that will be used to generate an SSL connection with your CloudSQL database. For more information, see link:https://docs.redhat.com/en/documentation/red_hat_quay/{producty}/html-single/securing_red_hat_quay/index#ssl-tls-quay-overview[SSL and TLS for {productname}]. |
| 10 | +* You have `base64 decoded` the original config bundle into a `config.yaml` file. For more information, see link:https://docs.redhat.com/en/documentation/red_hat_quay/{producty}/html-single/deploying_the_red_hat_quay_operator_on_openshift_container_platform/index#operator-config-cli-download[Downloading the existing configuration]. |
| 11 | +* You are using an externally managed PostgreSQL or CloudSQL database. For more information, see link:https://docs.redhat.com/en/documentation/red_hat_quay/{producty}/html-single/deploying_the_red_hat_quay_operator_on_openshift_container_platform/index#operator-unmanaged-postgres[Using and existing PostgreSQL database] with the `DB_URI` variable set. |
| 12 | +* Your externally managed PostgreSQL or CloudSQL database is configured for SSL/TLS. |
| 13 | +* The `postgres` component of your `QuayRegistry` CRD is set to `managed: false`, and your CloudSQL database is set with the `DB_URI` configuration variable. The following procedure uses `postgresql://<cloudsql_username>:<dbpassword>@<database_host>:<port>/<database_name>`. |
| 14 | +
|
| 15 | +.Procedure |
| 16 | + |
| 17 | +. After you have generated the CAs and SSL/TLS certificates and keys for your CloudSQL database and ensured that they are in `.pem` format, test the SSL connection to your CloudSQL server: |
| 18 | + |
| 19 | +.. Initiate a connection to your CloudSQL server by entering the following command: |
| 20 | ++ |
| 21 | +[source,terminal] |
| 22 | +---- |
| 23 | +$ psql "sslmode=verify-ca sslrootcert=<ssl_server_certificate_authority>.pem sslcert=<ssl_client_certificate>.pem sslkey=<ssl_client_key>.pem hostaddr=<34.29.130.58> port=<5432> user=<cloudsql_username> dbname=<cloudsql_database_name>" |
| 24 | +---- |
| 25 | + |
| 26 | +. In your {productname} directory, create a new YAML file, for example, `quay-config-bundle.yaml`, by running the following command: |
| 27 | ++ |
| 28 | +[source,terminal] |
| 29 | +---- |
| 30 | +$ touch quay-config-bundle.yaml |
| 31 | +---- |
| 32 | + |
| 33 | +. Create a `postgresql-client-certs` resource by entering the following command: |
| 34 | ++ |
| 35 | +[source,terminal] |
| 36 | +---- |
| 37 | +$ oc -n <quay_namespace> create secret generic postgresql-client-certs \ |
| 38 | +--from-file config.yaml=<path/to/config.yaml> <1> |
| 39 | +--from-file=tls.crt=<path/to/ssl_client_certificate.pem> <2> |
| 40 | +--from-file=tls.key=<path/to/ssl_client_key.pem> <3> |
| 41 | +--from-file=ca.crt=<path/to/ssl_server_certificate.pem> <4> |
| 42 | +---- |
| 43 | +<1> Where` <config.yaml>` is your `base64 decoded` `config.yaml` file. |
| 44 | +<2> Where `ssl_client_certificate.pem` is your SSL certificate in `.pem` format. |
| 45 | +<3> Where `ssl_client_key.pem` is your SSL key in `.pem` format. |
| 46 | +<4> Where `ssl_server_certificate.pem` is your SSL root CA in `.pem` format. |
| 47 | + |
| 48 | +. Edit your ``quay-config-bundle.yaml` file to include the following database connection settings: |
| 49 | ++ |
| 50 | +[IMPORTANT] |
| 51 | +==== |
| 52 | +* The information included in the `DB_CONNECTION_ARGS` variable, for example, `sslmode`, `sslrootcert`, `sslcert`, and `sslkey` *must* match the information appended to the `DB_URI` variable. Failure to match might result in a failed connection. |
| 53 | +* You cannot specify custom filenames or paths. Certificate file paths for `sslrootcert`, `sslcert`, and `sslkey` are hardcoded defaults and mounted into the `Quay` pod from the Kubernetes secret. You must adhere to the following naming conventions or it will result in a failed connection. |
| 54 | +==== |
| 55 | ++ |
| 56 | +[source,yaml] |
| 57 | +---- |
| 58 | +DB_CONNECTION_ARGS: |
| 59 | + autorollback: true |
| 60 | + sslmode: verify-ca <1> |
| 61 | + sslrootcert: /.postgresql/root.crt <2> |
| 62 | + sslcert: /.postgresql/postgresql.crt <3> |
| 63 | + sslkey: /.postgresql/postgresql.key <4> |
| 64 | + threadlocals: true <5> |
| 65 | +DB_URI: postgresql://<dbusername>:<dbpassword>@<database_host>:<port>/<database_name>?sslmode=verify-full&sslrootcert=/.postgresql/root.crt&sslcert=/.postgresql/postgresql.crt&sslkey=/.postgresql/postgresql.key <6> |
| 66 | +---- |
| 67 | +<1> Using `verify-ca` ensures that the database connection uses SSL/TLS and verifies the server certificate against a trusted CA. This can work with both trusted CA and self-signed CA certificates. However, this mode does not verify the hostname of the server. For full hostname and certificate verification, use `verify-full`. For more information about the configuration options available, see link:https://docs.redhat.com/en/documentation/red_hat_quay/{producty}/html-single/configure_red_hat_quay/index#config-fields-postgres[PostgreSQL SSL/TLS connection arguments]. |
| 68 | +<2> The `root.crt` file contains the root certificate used to verify the SSL/TLS connection with your CloudSQL database. This file is mounted in the `Quay` pod from the Kubernetes secret. |
| 69 | +<3> The `postgresql.crt` file contains the client certificate used to authenticate the connection to your CloudSQL database. This file is mounted in the `Quay` pod from the Kubernetes secret. |
| 70 | +<4> The `postgresql.key` file contains the private key associated with the client certificate. This file is mounted in the `Quay` pod from the Kubernetes secret. |
| 71 | +<5> Enables auto-rollback for connections. |
| 72 | +<6> The URI that accesses your CloudSQL database appended with your `root.crt`, `postgresql.crt`, and `postgresql.key` files. The SSL/TLS information included in `DB_URI` must match the information provided in `DB_CONNECTION_ARGS`. If you are using CloudSQL, you must include your database username and password in this variable. |
| 73 | +
|
| 74 | +. Create the `configBundleSecret` resource by entering the following command: |
| 75 | ++ |
| 76 | +[source,terminal] |
| 77 | +---- |
| 78 | +$ oc create -n <namespace> -f quay-config-bundle.yaml |
| 79 | +---- |
| 80 | ++ |
| 81 | +.Example output |
| 82 | ++ |
| 83 | +[source,terminal] |
| 84 | +---- |
| 85 | +secret/quay-config-bundle created |
| 86 | +---- |
| 87 | + |
| 88 | +. Update the `QuayRegistry` YAML file to reference the `quay-config-bundle` object by entering the following command: |
| 89 | ++ |
| 90 | +[source,terminal] |
| 91 | +---- |
| 92 | +$ oc patch quayregistry <registry_name> -n <namespace> --type=merge -p '{"spec":{"configBundleSecret":"quay-config-bundle"}}' |
| 93 | +---- |
| 94 | ++ |
| 95 | +.Example output |
| 96 | ++ |
| 97 | +[source,terminal] |
| 98 | +---- |
| 99 | +quayregistry.quay.redhat.com/example-registry patched |
| 100 | +---- |
| 101 | + |
| 102 | +. Ensure that your `QuayRegistry` YAML file has been updated to use the extra CA certificate `configBundleSecret` resource by entering the following command: |
| 103 | ++ |
| 104 | +[source,terminal] |
| 105 | +---- |
| 106 | +$ oc get quayregistry <registry_name> -n <namespace> -o yaml |
| 107 | +---- |
| 108 | ++ |
| 109 | +.Example output |
| 110 | ++ |
| 111 | +[source,terminal] |
| 112 | +---- |
| 113 | +# ... |
| 114 | + configBundleSecret: quay-config-bundle |
| 115 | +# ... |
| 116 | +---- |
0 commit comments