Note

We are no longer onboarding new users to Citus Cloud on AWS. However, existing customers can continue to use Citus Cloud as they do today.

Security

Connecting with SSL

For security Citus Cloud accepts only SSL connections, which is why the URL contains the ?sslmode=require parameter. Within the cluster, nodes also encrypt their communication with one another using SSL.

To avoid a man-in-the-middle attack when connecting to the coordinator node, clients can verify that the server certificate is correct. Download the official Citus Cloud certificate and refer to it in connection string parameters:

  1. ?sslrootcert=/location/to/citus.crt&sslmode=verify-full

The string may need to be quoted in your shell to preserve the ampersand.

Note

Database clients must support SSL to connect to Citus Cloud. In particular psql needs to be compiled --with-openssl if building PostgreSQL from source.

Application frameworks can customize database connection parameters using config files. For example, Ruby on Rails uses a file called config/database.yml. This file accepts sslmode and sslrootcert options to specify connection security. Here are two examples.

Requiring SSL for the production db connection:

  1. production:
  2.   adapter: postgresql
  3.   encoding: unicode
  4.   sslmode: require
  5.   url: postgres://user:password@host:port/db

Requiring SSL, plus verifying against a certificate:

  1. production:
  2.   adapter: postgresql
  3.   encoding: unicode
  4.   sslmode: verify-full
  5.   sslrootcert: /path/to/citus.crt
  6.   url: postgres://user:password@host:port/db

Two-Factor Authentication

We support two factor authentication for all Citus accounts. You can enable it from within your Citus Cloud account. We support Google Authenticator and Authy as two primary apps for setting up your two factor authentication.

Users and Permissions

As we saw above, every new Citus Cloud formation includes a user account called citus. This account is great for creating tables and other DDL, but it has too much power for certain applications.

We’ll want to create new roles for specialized purposes. For instance, a user with read-only access is perfect for a web/reporting tool. The Cloud console allows us to create a new user, and will set up a new password automatically. Go to the “Roles” tab and click “Create New Role.”

list of roles, with button to add another

It pops up a dialog where we will fill in the role name, which we can call reports.

form to set new role name

After creating the role on a fresh formation, there will be three roles:

  1. ┌─[ RECORD 1 ]────────────────────────────────────────────────────────────┐
  2. │ Role name  │ citus                                                      │
  3. │ Attributes │                                                            │
  4. │ Member of  │ {reports}                                                  │
  5. ├─[ RECORD 2 ]────────────────────────────────────────────────────────────┤
  6. │ Role name  │ postgres                                                   │
  7. │ Attributes │ Superuser, Create role, Create DB, Replication, Bypass RLS │
  8. │ Member of  │ {}                                                         │
  9. ├─[ RECORD 3 ]────────────────────────────────────────────────────────────┤
  10. │ Role name  │ reports                                                    │
  11. │ Attributes │                                                            │
  12. │ Member of  │ {}                                                         │
  13. └────────────┴────────────────────────────────────────────────────────────┘

The new reports role starts with no privileges, except “usage” on the public schema, meaning the ability to get a list of the tables etc inside. We have to specifically grant the role extra permissions to database objects. For instance, to allow read-only access to mytable, connect to Citus as the citus user with the connection string provided in the Cloud console and issue this command:

  1. -- run as the citus user
  3. GRANT SELECT ON mytable TO reports;

If mytable is in the public schema this will suffice. However, if the table is in another schema, there is one more step. See Granting Access to Other Schemas below.

You can confirm the privileges by consulting the information schema:

  1. SELECT grantee, privilege_type
  2.   FROM information_schema.role_table_grants
  3.  WHERE table_name = 'mytable';
  1. ┌─────────┬────────────────┐
  2. │ grantee │ privilege_type │
  3. ├─────────┼────────────────┤
  4. │ citus   │ INSERT         │
  5. │ citus   │ SELECT         │
  6. │ citus   │ UPDATE         │
  7. │ citus   │ DELETE         │
  8. │ citus   │ TRUNCATE       │
  9. │ citus   │ REFERENCES     │
  10. │ citus   │ TRIGGER        │
  11. │ reports │ SELECT         │
  12. └─────────┴────────────────┘

The PostgreSQL documentation has more detailed information about types of privileges you can GRANT on database objects.

Citus Cloud also supports Row-Level Security for greater control in a multi-tenant environment.

Granting Privileges in Bulk

Citus propagates single-table GRANT statements through the entire cluster, making them apply on all worker nodes. It also propagates GRANTs that are system-wide (e.g. for all tables in a schema):

  1. -- applies to the coordinator node and propagates to workers
  2. GRANT SELECT ON ALL TABLES IN SCHEMA public TO reports;

Granting Access to Other Schemas

By default, users cannot access objects in schemas they do not own. Note that by default, everyone has CREATE and USAGE privileges on the public schema. This allows all users that are able to connect to a given database to create objects in its public schema.

To allow object access in any other schema, the owner of the schema must grant the USAGE privilege on the schema.

  1. GRANT USAGE ON SCHEMA other_schema TO reports;

Even if the reports user has SELECT access on a table like other_schema.foo, the user will not be able to select rows until they also have USAGE access on other_schema.

Encryption at Rest

All data within Citus Cloud is encrypted at rest, including data on the instance as well as all backups for disaster recovery. As mentioned in the connection section, we also require that you connect to your database with TLS.

Network Perimeter Controls

All Citus Cloud clusters run in their own isolated Amazon Virtual Private Cloud (VPC). In addition to the options discussed earlier, Citus Cloud provides the ability to further secure your cluster by limiting network access in two ways:

VPC Peering

VPC peering forms a network connection between two VPCs which routes traffic securely between them using private IPv4 addresses or IPv6 addresses. Instances in either VPC can communicate with each other as if they are within the same network. To set up a VPC peering connecting between an existing Citus Cloud formation and an Amazon VPC, open a support ticket and we will initiate the peering request. Please keep in mind that inter-region VPC peering is currently not supported.

IP Whitelisting

IP whitelisting restricts access to servers within a Citus Cloud cluster so that only designated IP addresses are able to connect to them, typically the addresses of application servers.

To enable IP whitelisting on your Citus Cloud formation, go to the VPCs tab in the Cloud Console:

selected button saying "VPCs" in menu bar

Then find the VPC containing your formation and click View Details:

list of VPCs

Finally, in the “IP Whitelist / Ingress Rules” tab, enter the allowable IP addresses or CIDR blocks, one per line.

textbox with newline separated CIDR blocks

The special address 0.0.0.0/0 means unrestricted access. Note that permitted connections still require a valid username and password to actually access your database.