Add AWS EKS setup section (#250)

* Add AWS EKS setup section * Use the word instance instead of server for AWS
pganalyze · Apr 30, 2024 · 0ae9669 · 0ae9669
1 parent 0d7b581
commit 0ae9669
Show file tree

Hide file tree

Showing 23 changed files with 442 additions and 40 deletions.
diff --git a/components/MonitoringUserSetupInstructions.tsx b/components/MonitoringUserSetupInstructions.tsx
@@ -237,8 +237,8 @@ ${noPgMonitor ? '' : 'GRANT pg_monitor TO pganalyze;\n'}
 CREATE SCHEMA pganalyze;
 GRANT USAGE ON SCHEMA pganalyze TO pganalyze;
 GRANT USAGE ON SCHEMA public TO pganalyze;
-
-${noPgMonitor ? `CREATE OR REPLACE FUNCTION pganalyze.get_stat_replication() RETURNS SETOF pg_stat_replication AS
+${noPgMonitor ? `
+CREATE OR REPLACE FUNCTION pganalyze.get_stat_replication() RETURNS SETOF pg_stat_replication AS
 $$
   /* pganalyze-collector */ SELECT * FROM pg_catalog.pg_stat_replication;
 $$ LANGUAGE sql VOLATILE SECURITY DEFINER;` : ''}`}

diff --git a/directory.json b/directory.json
@@ -608,6 +608,10 @@
       "title": "Step 3: Install the Collector",
       "path": "/docs/install/amazon_rds/03_install_collector_ecs"
     },
+    "install/amazon_rds/03_install_collector_eks": {
+      "title": "Step 3: Install the Collector",
+      "path": "/docs/install/amazon_rds/03_install_collector_eks"
+    },
     "install/amazon_rds/04_configure_the_collector": {
       "title": "Step 4: Configure the Collector",
       "path": "/docs/install/amazon_rds/04_configure_the_collector"
@@ -624,6 +628,10 @@
       "title": "Step 4: Configure the Collector",
       "path": "/docs/install/amazon_rds/04_configure_the_collector_ecs"
     },
+    "install/amazon_rds/04_configure_the_collector_eks": {
+      "title": "Step 4: Configure the Collector",
+      "path": "/docs/install/amazon_rds/04_configure_the_collector_eks"
+    },
     "install/amazon_rds/iam_policy": {
       "title": "Amazon RDS and Aurora: IAM Policy",
       "path": "/docs/install/amazon_rds/iam_policy"

diff --git a/images/aws-eks.svg b/images/aws-eks.svg
diff --git a/install/amazon_rds/00_overview.mdx b/install/amazon_rds/00_overview.mdx
@@ -8,7 +8,7 @@ backlink_title: 'Installation Guide'
 import imgCollectorAwsArchitecture from '../../images/collector_aws_architecture.svg'
 export const ImgCollectorAwsArchitecture = () => <img src={imgCollectorAwsArchitecture} />
 
-To monitor your Amazon RDS for PostgreSQL or Amazon Aurora PostgreSQL servers
+To monitor your Amazon RDS for PostgreSQL or Amazon Aurora PostgreSQL instances
 with pganalyze, you need to run the pganalyze collector. The pganalyze collector
 connects to your database to capture query metadata and various statistics, then
 relays this information back to pganalyze on a continuous basis.
@@ -17,8 +17,8 @@ ECS, or with Docker.
 
 ## Prerequisites
 
-**Database Server**
-* Amazon RDS for PostgreSQL or Amazon Aurora PostgreSQL server to monitor
+**Database Instance**
+* Amazon RDS for PostgreSQL or Amazon Aurora PostgreSQL instance to monitor
 * PostgreSQL version 10 or above
 * Access with an RDS superuser (master user)
   * Required to create a monitoring user, extensions, and helper functions
@@ -30,8 +30,8 @@ ECS, or with Docker.
 * Capability to create an IAM policy/role for the collector
   * A new policy/role is required to access to the RDS metadata, Cloudwatch
     metrics, etc.
-* A direct connection to the PostgreSQL server
-  * The collector instance needs to be able to connect to the server directly,
+* A direct connection to the PostgreSQL instance
+  * The collector instance needs to be able to connect to the instance directly,
     bypass any connection poolers like PgBouncer
 
 Here is an overview diagram for how the pganalyze collector will be placed

diff --git a/install/amazon_rds/03_install_collector.mdx b/install/amazon_rds/03_install_collector.mdx
@@ -10,6 +10,7 @@ import styles from '../../style.module.scss'
 
 import imgAwsEc2 from '../../images/aws-ec2.svg'
 import imgAwsEcs from '../../images/aws-ecs.svg'
+import imgAwsEks from '../../images/aws-eks.svg'
 import imgDocker from '../../images/logo_docker.svg'
 
 export const SelectCollectorPlatform = () => {
@@ -27,6 +28,11 @@ export const SelectCollectorPlatform = () => {
           img: imgAwsEcs,
           providerName: "Amazon ECS",
         },
+        {
+          link: "03_install_collector_eks",
+          img: imgAwsEks,
+          providerName: "Amazon EKS",
+        },
         {
           link: "03_install_collector_docker",
           img: imgDocker,

diff --git a/install/amazon_rds/03_install_collector_ec2.mdx b/install/amazon_rds/03_install_collector_ec2.mdx
@@ -42,7 +42,7 @@ Then follow the step to install the collector on Amazon Linux 2 based instances.
 
 <CollectorInstallInstructions apiKey={props.apiKey} />
 
-After successful installation the pganalyze collector will now be running in the background on your server.
+After successful installation the pganalyze collector will now be running in the background on your instance.
 
 <Link className="btn btn-success" to="04_configure_the_collector_ec2">
   Proceed to Step 4: Configure the Collector

diff --git a/install/amazon_rds/03_install_collector_ecs.mdx b/install/amazon_rds/03_install_collector_ecs.mdx
@@ -15,8 +15,8 @@ We will launch this container as a single persistent task using an [ECS service]
 
 ### Create IAM role
 
-We'll need need a special IAM role to run the container with. The following
-commands will create an appropriate role.
+We'll need a special IAM role to run the container with. The following commands
+will create an appropriate role.
 This assumes you are using your account's default KMS key for accessing SSM
 parameters.
 

diff --git a/install/amazon_rds/03_install_collector_eks.mdx b/install/amazon_rds/03_install_collector_eks.mdx
@@ -0,0 +1,34 @@
+---
+title: 'Step 3: Install the Collector'
+install_track_title: Installation Guide (Amazon RDS and Amazon Aurora)
+backlink_href: /docs/install
+backlink_title: 'Installation Guide'
+---
+
+import SetupIAMPolicy from './_03_setup_iam_policy.mdx';
+import CreateIAMRoleEKSIRSA from './_03_create_iam_role_eks_irsa.mdx'
+
+## Installing the collector with Amazon EKS
+
+You can install the Helm chart for the pganalyze collector on your [Amazon EKS cluster](https://docs.aws.amazon.com/eks/latest/userguide/what-is-eks.html).
+
+### Prerequisites
+
+* You already have an Amazon EKS cluster
+* [`kubectl`](https://kubernetes.io/docs/tasks/tools/) is installed
+* [`eksctl`](https://eksctl.io/installation/) is installed and [a kubeconfig file for an Amazon EKS cluster is created](https://docs.aws.amazon.com/eks/latest/userguide/create-kubeconfig.html)
+* [`The Helm CLI`](https://helm.sh/) v3 or above is installed
+
+<SetupIAMPolicy />
+
+### Create IAM role
+
+**Note:** Creating an IAM role currently requires using IAM roles for service
+accounts (IRSA). Creating an IAM role with Amazon EKS Pod Identity is not
+supported yet.
+
+<CreateIAMRoleEKSIRSA />
+
+<Link className="btn btn-success" to="04_configure_the_collector_eks">
+  Proceed to Step 4: Configure the Collector
+</Link>
diff --git a/install/amazon_rds/04_configure_the_collector.mdx b/install/amazon_rds/04_configure_the_collector.mdx
@@ -10,6 +10,7 @@ import styles from '../../style.module.scss'
 
 import imgAwsEc2 from '../../images/aws-ec2.svg'
 import imgAwsEcs from '../../images/aws-ecs.svg'
+import imgAwsEks from '../../images/aws-eks.svg'
 import imgDocker from '../../images/logo_docker.svg'
 
 export const SelectCollectorPlatform = () => {
@@ -27,6 +28,11 @@ export const SelectCollectorPlatform = () => {
           img: imgAwsEcs,
           providerName: "Amazon ECS",
         },
+        {
+          link: "04_configure_the_collector_eks",
+          img: imgAwsEks,
+          providerName: "Amazon EKS",
+        },
         {
           link: "04_configure_the_collector_docker",
           img: imgDocker,

diff --git a/install/amazon_rds/04_configure_the_collector_docker.mdx b/install/amazon_rds/04_configure_the_collector_docker.mdx
@@ -24,17 +24,17 @@ In the case of Amazon Aurora, the collector automatically resolves `cluster` end
 DB_HOST=mydbcluster.cluster-123456789012.us-east-1.rds.amazonaws.com
 ```
 
-This will only monitor the writer instance. If you also want to monitor a reader instance, you'll need to use the Multiple Servers method above.
+This will only monitor the writer instance. If you also want to monitor a reader instance, you'll need to use the Multiple Instances method above.
 
 ```
 CONFIG_CONTENTS="[pganalyze]
 api_key = 'your_pga_organization_api_key'
 
-[server_writer]
+[writer_instance]
 db_host = mydbcluster.cluster-123456789012.us-east-1.rds.amazonaws.com
 ...
 
-[server_reader]
+[reader_instance]
 db_host = mydbcluster.cluster-ro-123456789012.us-east-1.rds.amazonaws.com
 ...
 "

diff --git a/install/amazon_rds/04_configure_the_collector_ec2.mdx b/install/amazon_rds/04_configure_the_collector_ec2.mdx
@@ -26,7 +26,7 @@ export const ConfigSample = ({ apiKey }) => {
     <CodeBlock>
       {`[pganalyze]
 api_key = ${apiKey ?? 'your_pga_organization_api_key'}\n
-[server1]
+[instance1]
 db_host = instance-id.account-id.us-east-1.rds.amazonaws.com
 db_name = your_database_name
 db_username = your_monitoring_user
@@ -47,7 +47,7 @@ The collector configuration file lives in `/etc/pganalyze-collector.conf`, and l
 
 1. <APIKeyInstructions apiKey={props.apiKey} />
 2. The `db_host` is the hostname / endpoint of your RDS instance (for Amazon Aurora you can use the cluster endpoint in many cases, see for details below)
-3. The `db_name` is the database name on the Postgres server you want to monitor
+3. The `db_name` is the database name on the Postgres instance you want to monitor
 4. The `db_username` and `db_password` should be the monitoring user we created in <Link to='02_create_monitoring_user'>Step 2</Link>
 5. The `db_sslrootcert` and `db_sslmode` is the recommended SSL connection configuration that you can usually keep as specified above
 
@@ -58,11 +58,11 @@ The collector configuration file lives in `/etc/pganalyze-collector.conf`, and l
 In the case of Amazon Aurora, the collector automatically resolves `cluster` endpoints to the underlying writer instance, and `cluster-ro` to the underlying reader instance:
 
 ```
-[server_writer]
+[writer_instance]
 db_host = mydbcluster.cluster-123456789012.us-east-1.rds.amazonaws.com
 ...
 
-[server_reader]
+[reader_instance]
 db_host = mydbcluster.cluster-ro-123456789012.us-east-1.rds.amazonaws.com
 ...
 ```
@@ -73,15 +73,15 @@ reader instances this is only supported in two-node clusters (i.e. single reader
 If you have multiple readers you want to monitor you instead need to specify each instance endpoint separately:
 
 ```
-[server_instance1]
+[instance1]
 db_host = mydbinstance1.123456789012.us-east-1.rds.amazonaws.com
 ...
 
-[server_instance2]
+[instance2]
 db_host = mydbinstance2.123456789012.us-east-1.rds.amazonaws.com
 ...
 
-[server_instance3]
+[instance3]
 db_host = mydbinstance3.123456789012.us-east-1.rds.amazonaws.com
 ...
 ```

diff --git a/install/amazon_rds/04_configure_the_collector_ecs.mdx b/install/amazon_rds/04_configure_the_collector_ecs.mdx
@@ -32,19 +32,19 @@ In the case of Amazon Aurora, the collector automatically resolves `cluster` end
 ```
 
 This will only monitor the writer instance. If you also want to monitor a reader instance,
-you'll need to use the Multiple Servers method above and specify the reader instance as a
-second server within the `pganalyze_collector.conf` file, then update the `/pganalyze/CONFIG_CONTENTS`
+you'll need to use the Multiple Instances method above and specify the reader instance as a
+second instance within the `pganalyze_collector.conf` file, then update the `/pganalyze/CONFIG_CONTENTS`
 SSM secret.
 
 ```
 [pganalyze]
 api_key = 'your_pga_organization_api_key'
 
-[server_writer]
+[writer_instance]
 db_host = mydbcluster.cluster-123456789012.us-east-1.rds.amazonaws.com
 ...
 
-[server_reader]
+[reader_instance]
 db_host = mydbcluster.cluster-ro-123456789012.us-east-1.rds.amazonaws.com
 ...
 ```