From 3820346a4fd6717835af060549d8f8989b33d6b2 Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Fri, 22 Mar 2024 14:01:07 +0100 Subject: [PATCH 1/7] docs: describe operational readiness --- docs/admin/architectures/index.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/admin/architectures/index.md b/docs/admin/architectures/index.md index 2ff758a04bd52..b2e3eebbcb5c0 100644 --- a/docs/admin/architectures/index.md +++ b/docs/admin/architectures/index.md @@ -342,3 +342,17 @@ We provide the following general recommendations for PostgreSQL settings: and memory utilization is high. - Utilize faster disk options (higher IOPS) such as SSDs or NVMe drives for optimal performance enhancement and possibly reduce database load. + +## Operational readiness + +TODO Configuration: Helm values, environment variables + +TODO Template configuration managed via CI/CD. + +TODO Observability, e.g. Promethus/Grafana + +TODO Database backups link scripts if we have any + +TODO Custom support links + +TODO Custom agent troubleshooting links From ce16dfe4749b1e8477fdcb1e0a8d7298d5f3d988 Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Fri, 22 Mar 2024 15:31:15 +0100 Subject: [PATCH 2/7] Agenda --- docs/admin/architectures/index.md | 36 +++++++++++++++++++++++++------ 1 file changed, 30 insertions(+), 6 deletions(-) diff --git a/docs/admin/architectures/index.md b/docs/admin/architectures/index.md index b2e3eebbcb5c0..24b38cac5f124 100644 --- a/docs/admin/architectures/index.md +++ b/docs/admin/architectures/index.md @@ -345,14 +345,38 @@ We provide the following general recommendations for PostgreSQL settings: ## Operational readiness -TODO Configuration: Helm values, environment variables +Operational readiness in Coder is about ensuring that everything is set up +correctly before launching a platform into production. It involves making sure +that the service is reliable, secure, and easily scales accordingly to user-base +needs. Operational readiness is crucial because it helps prevent issues that +could affect workspace users experience once the platform is live. -TODO Template configuration managed via CI/CD. +### Configuration -TODO Observability, e.g. Promethus/Grafana +#### Helm values -TODO Database backups link scripts if we have any +TODO -TODO Custom support links +#### Environment variables -TODO Custom agent troubleshooting links +TODO + +### Template configuration + +TODO managed via CI/CD + +### Observability + +TODO Prometheus, Grafana, logging + +### Database backups + +TODO link scripts if we have any + +### Support links + +TODO + +### Troubleshooting agent + +TODO links From bbe13387c799da97d4de0a897d287d6cfd8297f6 Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Fri, 22 Mar 2024 16:59:58 +0100 Subject: [PATCH 3/7] TODOs done --- docs/admin/architectures/index.md | 43 +++++++++++++++++++------------ 1 file changed, 27 insertions(+), 16 deletions(-) diff --git a/docs/admin/architectures/index.md b/docs/admin/architectures/index.md index 24b38cac5f124..22193411de261 100644 --- a/docs/admin/architectures/index.md +++ b/docs/admin/architectures/index.md @@ -351,32 +351,43 @@ that the service is reliable, secure, and easily scales accordingly to user-base needs. Operational readiness is crucial because it helps prevent issues that could affect workspace users experience once the platform is live. -### Configuration - -#### Helm values - -TODO +Learn about Coder design principles and architectural best practices described +in the +[Well-Architected Framework](https://coder.com/blog/coder-well-architected-framework). -#### Environment variables +### Configuration -TODO +1. Create `values.yaml` and add it to a version control system. +1. Determine the necessary environment variables. +1. Identify the required Helm values for configuration. ### Template configuration -TODO managed via CI/CD +1. Establish a dedicated user account for the _Template Administrator_. +1. Maintain Coder templates using version control. +1. Consider implementing a GitOps workflow to automatically push new template + versions to Coder. +1. Evaluate enabling automatic template updates upon workspace startup. ### Observability -TODO Prometheus, Grafana, logging +1. Enable the Prometheus endpoint (environment variable: + `CODER_PROMETHEUS_ENABLE`). +1. Deploy a visual monitoring system such as Grafana for metrics visualization. +1. Deploy a centralized logs aggregation solution to collect and monitor + application logs. +1. Review the [Prometheus response](../prometheus.md) and set up alarms on + selected metrics. ### Database backups -TODO link scripts if we have any - -### Support links - -TODO +1. Prepare internal scripts for dumping and restoring databases. +1. Schedule regular database backups, especially before release upgrades. -### Troubleshooting agent +### User support -TODO links +1. Incorporate [support links](../appearance.md#support-links) into internal + documentation accessible from the user context menu. Ensure that hyperlinks + are valid and lead to up-to-date materials. +1. Encourage the use of `coder support bundle` to allow workspace users to + generate and provide network-related diagnostic data. From ef1806b29dc81a5e90fc3dc2444fd3f11fb1a53e Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Mon, 25 Mar 2024 13:56:14 +0100 Subject: [PATCH 4/7] Cian's feedback --- docs/admin/architectures/index.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/docs/admin/architectures/index.md b/docs/admin/architectures/index.md index 22193411de261..5b147b76e7e6d 100644 --- a/docs/admin/architectures/index.md +++ b/docs/admin/architectures/index.md @@ -357,18 +357,26 @@ in the ### Configuration -1. Create `values.yaml` and add it to a version control system. -1. Determine the necessary environment variables. 1. Identify the required Helm values for configuration. +1. Create `values.yaml` and add it to a version control system. _Note:_ it is + highly recommended that you create a custom `values.yaml` as opposed to + copying the entire default values. +1. Determine the necessary environment variables. ### Template configuration 1. Establish a dedicated user account for the _Template Administrator_. 1. Maintain Coder templates using version control. -1. Consider implementing a GitOps workflow to automatically push new template - versions to Coder. +1. Consider implementing a GitOps workflow to automatically push new template. + For example, on Github, you can use the + [Update Coder Template](https://github.com/marketplace/actions/update-coder-template) + action. 1. Evaluate enabling automatic template updates upon workspace startup. +### Deployment + +1. Leverage automation tooling to automate deployment and upgrades of Coder. + ### Observability 1. Enable the Prometheus endpoint (environment variable: From 0aac70fecc87245667cf5901790ca0ff05cf3852 Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Mon, 25 Mar 2024 14:01:26 +0100 Subject: [PATCH 5/7] make no j --- .github/workflows/ci.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 8db445e798f42..93517d2baa36b 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -605,7 +605,7 @@ jobs: uses: ./.github/actions/setup-sqlc - name: make gen - run: "make --output-sync -j -B gen" + run: "make --output-sync -B gen" - name: Format run: | From 0d45c2cf401f4f52b13eae58e4eb7beaab263642 Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Mon, 25 Mar 2024 14:08:49 +0100 Subject: [PATCH 6/7] make no j --- .github/workflows/ci.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 93517d2baa36b..71945dda2b1b9 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -202,7 +202,7 @@ jobs: popd - name: make gen - run: "make --output-sync -j -B gen" + run: "make --output-sync -B gen" - name: Check for unstaged files run: ./scripts/check_unstaged.sh From d8c5708b757a92d753a9a0bd6796324e235ec3fa Mon Sep 17 00:00:00 2001 From: Marcin Tojek Date: Mon, 25 Mar 2024 14:14:44 +0100 Subject: [PATCH 7/7] comment --- .github/workflows/ci.yaml | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 71945dda2b1b9..65e971981c111 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -202,6 +202,8 @@ jobs: popd - name: make gen + # no `-j` flag as `make` fails with: + # coderd/rbac/object_gen.go:1:1: syntax error: package statement must be first run: "make --output-sync -B gen" - name: Check for unstaged files @@ -604,9 +606,6 @@ jobs: - name: Setup sqlc uses: ./.github/actions/setup-sqlc - - name: make gen - run: "make --output-sync -B gen" - - name: Format run: | cd offlinedocs @@ -618,8 +617,10 @@ jobs: pnpm lint - name: Build + # no `-j` flag as `make` fails with: + # coderd/rbac/object_gen.go:1:1: syntax error: package statement must be first run: | - make -j build/coder_docs_"$(./scripts/version.sh)".tgz + make build/coder_docs_"$(./scripts/version.sh)".tgz required: runs-on: ubuntu-latest