From 7509eaacb3fdb6d793f376dd75cb7fde07a47495 Mon Sep 17 00:00:00 2001 From: Trong Huu Nguyen Date: Wed, 15 May 2024 10:49:27 +0200 Subject: [PATCH] Reapply "Restructure to 'diataxis by feature' (#640)" This reverts commit 8db977d4d421edb34663c16f74a3a2bb25ad96fe. Co-authored-by: Johnny Horvi --- build.sh | 4 +- docs/.pages | 17 + docs/README.md | 59 ++- docs/authentication/.pages | 1 + docs/authentication/machines/README.md | 1 + docs/authentication/users/README.md | 1 + docs/build/.pages | 5 + docs/build/README.md | 25 ++ .../how-to/build-and-deploy.md} | 12 +- .../how-to}/dependabot-auto-merge.md | 4 + docs/explanation/.pages | 9 - docs/explanation/README.md | 3 - docs/explanation/database/opensearch.md | 0 docs/explanation/naisdevice.md | 9 - docs/explanation/restoring.md | 5 - docs/explanation/team.md | 20 - docs/explanation/under-the-hood.md | 54 --- docs/explanation/workloads/README.md | 11 - docs/explanation/workloads/application.md | 11 - docs/explanation/workloads/job.md | 7 - docs/explanation/zero-trust.md | 42 -- docs/explanations/.pages | 4 + docs/{explanation => explanations}/nais.md | 6 +- docs/explanations/team.md | 30 ++ docs/explanations/under-the-hood.md | 75 ++++ docs/how-to-guides/.pages | 1 - docs/how-to-guides/README.md | 4 - docs/how-to-guides/command-line-access/.pages | 1 - .../command-line-access/troubleshooting.md | 8 - .../communicating-inside-environment.md | 24 -- docs/how-to-guides/exposing-an-application.md | 26 -- docs/how-to-guides/nais-cli/.pages | 1 - docs/how-to-guides/naisdevice/.pages | 1 - docs/how-to-guides/naisdevice/install.md | 102 ----- docs/how-to-guides/persistence/.pages | 6 - .../how-to-guides/persistence/bigquery/.pages | 1 - docs/how-to-guides/persistence/redis/.page | 1 - docs/how-to-guides/secrets/.pages | 4 - .../how-to-guides/workload-crud-operations.md | 77 ---- docs/observability/.pages | 5 + .../{explanation => }/observability/README.md | 15 +- docs/observability/alerting/.pages | 5 + .../alerting/README.md} | 5 +- .../alerting/how-to}/grafana.md | 21 +- .../alerting/how-to}/prometheus-advanced.md | 9 +- .../alerting/how-to}/prometheus-basic.md | 22 +- .../alerting/reference}/prometheusrule.md | 7 +- .../frontend/README.md} | 5 +- .../how-to}/auto-instrumentation.md | 7 +- docs/observability/logging/.pages | 5 + .../logging/README.md} | 7 +- .../logging/how-to}/disable.md | 3 +- .../logging/how-to}/kubectl.md | 13 +- .../logging/how-to}/loki.md | 7 +- .../logging/reference}/logql.md | 4 +- docs/observability/metrics/.pages | 5 + .../metrics/README.md} | 11 +- .../metrics/how-to}/dashboard.md | 3 +- .../metrics/how-to}/expose.md | 6 +- .../metrics/how-to}/push.md | 6 +- .../metrics/reference}/globals.md | 0 .../metrics/reference}/grafana.md | 6 +- .../metrics}/reference/metrics.md | 6 +- .../metrics/reference}/otel.md | 4 + .../metrics/reference}/promql.md | 7 +- .../reference}/auto-config.md | 10 +- .../{ => observability}/reference/glossary.md | 6 +- docs/observability/tracing/.pages | 5 + .../tracing/README.md} | 8 +- .../tracing/how-to}/context-propagation.md | 7 +- .../tracing/how-to}/correlate-traces-logs.md | 15 +- .../tracing/how-to}/tempo.md | 10 +- .../tracing/reference}/trace-semconv.md | 4 + .../tracing/reference}/traceql.md | 4 +- docs/operate/.pages | 7 + docs/operate/README.md | 18 + docs/operate/cli/.pages | 5 + docs/operate/cli/README.md | 30 ++ .../cli/how-to}/install.md | 6 +- .../cli/how-to}/troubleshooting.md | 6 +- .../cli => operate/cli/reference}/device.md | 6 +- .../cli/reference}/kubeconfig.md | 4 + .../cli => operate/cli/reference}/postgres.md | 4 + .../cli => operate/cli/reference}/validate.md | 10 +- docs/operate/console.md | 13 + .../how-to/command-line-access.md} | 34 +- .../team.md => operate/how-to/create-team.md} | 16 +- docs/operate/naisdevice/.pages | 4 + docs/operate/naisdevice/README.md | 20 + .../operate/naisdevice/how-to}/install.md | 132 ++++++- .../naisdevice/how-to}/troubleshooting.md | 6 +- docs/operate/naisdevice/how-to/uninstall.md | 95 +++++ .../naisdevice/how-to}/update.md | 4 + docs/persistence/.pages | 4 + docs/persistence/README.md | 117 ++++++ docs/persistence/bigquery/.pages | 5 + .../bigquery/README.md} | 12 +- .../bigquery/how-to}/connect.md | 4 + .../bigquery/how-to}/create.md | 6 +- docs/persistence/buckets/.pages | 5 + docs/persistence/buckets/README.md | 10 + .../buckets/how-to}/create.md | 16 +- .../buckets/how-to}/delete.md | 7 +- .../buckets/reference.md} | 10 +- .../explanations/responsibilities.md | 61 +++ docs/persistence/kafka/.pages | 5 + .../kafka.md => persistence/kafka/README.md} | 24 ++ .../kafka/how-to}/access.md | 23 +- .../kafka/how-to}/create.md | 14 +- .../kafka/how-to}/delete.md | 12 +- .../kafka/how-to}/internal.md | 12 +- .../kafka/how-to}/manage-acl.md | 16 +- .../kafka/how-to}/monitoring.md | 4 + .../kafka/how-to}/remove-access.md | 12 +- .../kafka/how-to}/schema-operations.md | 4 + .../kafka/reference/environment-variables.md} | 24 +- .../kafka}/reference/kafka-topic-example.md | 0 .../kafka}/reference/kafka-topic-spec.md | 0 docs/persistence/opensearch/.pages | 7 + .../persistence/opensearch/README.md | 8 +- .../opensearch/how-to}/create.md | 6 +- .../opensearch/reference.md} | 8 +- .../persistence/postgres/README.md | 72 ++-- docs/persistence/redis/.pages | 5 + docs/persistence/redis/README.md | 14 + .../redis/how-to/create-application.md} | 38 +- .../redis/how-to/create-explicit.md} | 17 +- .../redis/reference.md} | 17 +- docs/reference/README.md | 3 - docs/reference/access-policy.md | 365 ------------------ docs/reference/cli/.pages | 1 - docs/reference/default-variables.md | 12 - docs/reference/deploy-action-config.md | 24 -- docs/reference/environments.md | 3 - docs/reference/kyverno-policies.md | 120 ------ docs/reference/secrets.md | 45 --- docs/reference/service-discovery.md | 80 ---- docs/security/.pages | 5 - docs/security/README.md | 21 +- docs/security/auth/.pages | 16 +- docs/security/auth/README.md | 1 + docs/security/auth/azure-ad/.pages | 11 +- docs/security/auth/azure-ad/README.md | 1 + docs/security/auth/azure-ad/configuration.md | 7 +- .../auth/azure-ad/faq-troubleshooting.md | 3 + docs/security/auth/azure-ad/sidecar.md | 7 +- docs/security/auth/azure-ad/usage.md | 3 + docs/security/auth/concepts.md | 4 + docs/security/auth/development.md | 4 + docs/security/auth/idporten.md | 7 +- docs/security/auth/maskinporten/README.md | 1 + docs/security/auth/maskinporten/client.md | 8 +- docs/security/auth/maskinporten/scopes.md | 6 +- docs/security/auth/tokenx.md | 3 +- docs/security/auth/wonderwall.md | 15 +- docs/services/.pages | 6 + docs/services/README.md | 12 + docs/{security => services}/antivirus.md | 3 +- docs/services/cdn/.pages | 5 + .../cdn.md => services/cdn/README.md} | 9 +- .../cdn/how-to/upload-assets.md} | 20 +- .../cdn.md => services/cdn/reference.md} | 9 +- .../feature-toggling.md | 4 + docs/services/leader-election/.pages | 4 + .../leader-election/README.md} | 6 +- .../leader-election/how-to/enable.md} | 8 +- .../salsa/README.md => services/salsa.md} | 3 +- docs/services/secrets/.pages | 5 + .../secrets.md => services/secrets/README.md} | 14 +- .../secrets/how-to}/console.md | 8 +- .../secrets/how-to}/workload.md | 12 +- docs/services/secrets/reference.md | 56 +++ docs/{reference => }/tags.md | 0 docs/tutorial/.pages | 1 - docs/tutorial/README.md | 20 - docs/tutorial/hello-nais/hello-nais-1.md | 53 --- docs/tutorial/hello-nais/hello-nais-2.md | 101 ----- docs/tutorial/hello-nais/hello-nais-3.md | 46 --- docs/tutorial/hello-nais/hello-nais-4.md | 24 -- docs/tutorials/.pages | 4 + docs/tutorials/README.md | 21 + docs/tutorials/hello-nais.md | 225 +++++++++++ docs/workloads/.pages | 8 + docs/workloads/README.md | 35 ++ docs/workloads/application/.pages | 6 + docs/workloads/application/README.md | 27 ++ .../application/explanations/expose.md} | 13 +- docs/workloads/application/how-to/create.md | 65 ++++ docs/workloads/application/how-to/delete.md | 24 ++ docs/workloads/application/how-to/expose.md | 27 ++ .../reference/application-example.md | 6 +- .../reference/application-spec.md | 4 + .../reference/automatic-scaling.md | 112 ++++++ .../explanations}/environment.md | 9 +- .../explanations}/good-practices.md | 19 +- docs/workloads/explanations/zero-trust.md | 75 ++++ .../how-to}/access-policies.md | 14 +- docs/workloads/how-to/communication.md | 42 ++ docs/workloads/job/.pages | 5 + docs/workloads/job/README.md | 23 ++ docs/workloads/job/how-to/create.md | 57 +++ docs/workloads/job/how-to/delete.md | 24 ++ .../job}/reference/naisjob-example.md | 2 +- .../job}/reference/naisjob-spec.md | 0 docs/workloads/reference/access-policies.md | 17 + docs/workloads/reference/default-variables.md | 15 + docs/workloads/reference/environments.md | 108 ++++++ docs/{ => workloads}/reference/ingress.md | 41 +- docs/{ => workloads}/reference/json-schema.md | 4 + flake.lock | 6 +- flake.nix | 13 +- mkdocs.yml | 33 +- .../how-to}/oci-migration.md | 17 +- .../explanation/migrating-databases-to-gcp.md | 161 -------- tenants/nav/explanation/migrating-to-gcp.md | 204 ---------- tenants/nav/explanation/naisdevice.md | 12 - .../persistence/influxdb/datasource.md | 15 - tenants/nav/{reference => }/legal/app-pvk.md | 4 +- tenants/nav/{reference => }/legal/app-ros.md | 0 .../nav/{reference => }/legal/arkivloven.md | 0 .../nav/{reference => }/legal/dpa/README.md | 0 .../{reference => }/legal/dpa/aiven-dpa.md | 2 +- .../{reference => }/legal/dpa/azure-dpa.md | 0 .../nav/{reference => }/legal/dpa/gcp-dpa.md | 0 tenants/nav/{reference => }/legal/nais-pvk.md | 2 +- tenants/nav/{reference => }/legal/nais-ros.md | 0 .../legal/roles-responsibilities.md | 0 .../logging/how-to}/access-secure-logs.md | 15 +- .../logging/how-to}/audit-logs.md | 4 + .../logging/how-to}/enable-secure-logs.md | 14 +- .../logging/how-to}/kibana.md | 4 +- .../logging/reference}/kql.md | 4 +- .../how-to}/grafana-from-infoscreen.md | 2 +- .../cli => operate/cli/reference}/aiven.md | 30 +- .../cli => operate/cli/reference}/device.md | 12 +- tenants/nav/operate/naisdevice/.pages | 4 + .../naisdevice/explanations}/jita.md | 10 +- .../naisdevice/how-to}/install-kolide.md | 4 + .../naisdevice/how-to}/troubleshooting.md | 6 +- .../naisdevice/how-to}/uninstall-kolide.md | 4 + tenants/nav/persistence/influxdb/.pages | 5 + tenants/nav/persistence/influxdb/README.md | 53 +++ .../influxdb/how-to}/access.md | 5 +- .../influxdb/how-to}/create.md | 9 +- tenants/nav/persistence/influxdb/reference.md | 28 ++ .../kafka/how-to}/access-from-non-nais.md | 14 +- .../how-to}/renew-credentials-for-non-nais.md | 12 +- tenants/nav/persistence/postgres/.pages | 4 + .../how-to}/migrating-databases-to-gcp.md | 8 +- tenants/nav/reference/environments.md | 70 ---- .../expose-fss-apps-with-maskinporten.md | 5 +- .../explanations/migrating-to-gcp.md | 226 +++++++++++ tenants/ssb/reference/environments.md | 31 -- 253 files changed, 2889 insertions(+), 2354 deletions(-) create mode 100644 docs/.pages create mode 100644 docs/authentication/.pages create mode 100644 docs/authentication/machines/README.md create mode 100644 docs/authentication/users/README.md create mode 100644 docs/build/.pages create mode 100644 docs/build/README.md rename docs/{how-to-guides/github-action.md => build/how-to/build-and-deploy.md} (86%) rename docs/{how-to-guides => build/how-to}/dependabot-auto-merge.md (99%) delete mode 100644 docs/explanation/.pages delete mode 100644 docs/explanation/README.md delete mode 100644 docs/explanation/database/opensearch.md delete mode 100644 docs/explanation/naisdevice.md delete mode 100644 docs/explanation/restoring.md delete mode 100644 docs/explanation/team.md delete mode 100644 docs/explanation/under-the-hood.md delete mode 100644 docs/explanation/workloads/README.md delete mode 100644 docs/explanation/workloads/application.md delete mode 100644 docs/explanation/workloads/job.md delete mode 100644 docs/explanation/zero-trust.md create mode 100644 docs/explanations/.pages rename docs/{explanation => explanations}/nais.md (93%) create mode 100644 docs/explanations/team.md create mode 100644 docs/explanations/under-the-hood.md delete mode 100644 docs/how-to-guides/.pages delete mode 100644 docs/how-to-guides/README.md delete mode 100644 docs/how-to-guides/command-line-access/.pages delete mode 100644 docs/how-to-guides/command-line-access/troubleshooting.md delete mode 100644 docs/how-to-guides/communicating-inside-environment.md delete mode 100644 docs/how-to-guides/exposing-an-application.md delete mode 100644 docs/how-to-guides/nais-cli/.pages delete mode 100644 docs/how-to-guides/naisdevice/.pages delete mode 100644 docs/how-to-guides/naisdevice/install.md delete mode 100644 docs/how-to-guides/persistence/.pages delete mode 100644 docs/how-to-guides/persistence/bigquery/.pages delete mode 100644 docs/how-to-guides/persistence/redis/.page delete mode 100644 docs/how-to-guides/secrets/.pages delete mode 100644 docs/how-to-guides/workload-crud-operations.md create mode 100644 docs/observability/.pages rename docs/{explanation => }/observability/README.md (93%) create mode 100644 docs/observability/alerting/.pages rename docs/{explanation/observability/alerting.md => observability/alerting/README.md} (98%) rename docs/{how-to-guides/observability/alerts => observability/alerting/how-to}/grafana.md (85%) rename docs/{how-to-guides/observability/alerts => observability/alerting/how-to}/prometheus-advanced.md (97%) rename docs/{how-to-guides/observability/alerts => observability/alerting/how-to}/prometheus-basic.md (84%) rename docs/{reference/observability/alerts => observability/alerting/reference}/prometheusrule.md (91%) rename docs/{explanation/observability/frontend.md => observability/frontend/README.md} (97%) rename docs/{how-to-guides/observability => observability/how-to}/auto-instrumentation.md (89%) create mode 100644 docs/observability/logging/.pages rename docs/{explanation/observability/logging.md => observability/logging/README.md} (94%) rename docs/{how-to-guides/observability/logs => observability/logging/how-to}/disable.md (95%) rename docs/{how-to-guides/observability/logs => observability/logging/how-to}/kubectl.md (60%) rename docs/{how-to-guides/observability/logs => observability/logging/how-to}/loki.md (81%) rename docs/{reference/observability/logs => observability/logging/reference}/logql.md (96%) create mode 100644 docs/observability/metrics/.pages rename docs/{explanation/observability/metrics.md => observability/metrics/README.md} (94%) rename docs/{how-to-guides/observability/metrics => observability/metrics/how-to}/dashboard.md (98%) rename docs/{how-to-guides/observability/metrics => observability/metrics/how-to}/expose.md (79%) rename docs/{how-to-guides/observability/metrics => observability/metrics/how-to}/push.md (93%) rename docs/{reference/observability/metrics => observability/metrics/reference}/globals.md (100%) rename docs/{reference/observability/metrics => observability/metrics/reference}/grafana.md (87%) rename docs/{ => observability/metrics}/reference/metrics.md (80%) rename docs/{reference/observability/metrics => observability/metrics/reference}/otel.md (98%) rename docs/{reference/observability/metrics => observability/metrics/reference}/promql.md (89%) rename docs/{reference/observability => observability/reference}/auto-config.md (94%) rename docs/{ => observability}/reference/glossary.md (97%) create mode 100644 docs/observability/tracing/.pages rename docs/{explanation/observability/tracing.md => observability/tracing/README.md} (95%) rename docs/{how-to-guides/observability/tracing => observability/tracing/how-to}/context-propagation.md (88%) rename docs/{how-to-guides/observability/tracing => observability/tracing/how-to}/correlate-traces-logs.md (91%) rename docs/{how-to-guides/observability/tracing => observability/tracing/how-to}/tempo.md (93%) rename docs/{reference/observability/tracing => observability/tracing/reference}/trace-semconv.md (76%) rename docs/{reference/observability/tracing => observability/tracing/reference}/traceql.md (97%) create mode 100644 docs/operate/.pages create mode 100644 docs/operate/README.md create mode 100644 docs/operate/cli/.pages create mode 100644 docs/operate/cli/README.md rename docs/{how-to-guides/nais-cli => operate/cli/how-to}/install.md (95%) rename docs/{how-to-guides/nais-cli => operate/cli/how-to}/troubleshooting.md (95%) rename docs/{reference/cli => operate/cli/reference}/device.md (94%) rename docs/{reference/cli => operate/cli/reference}/kubeconfig.md (96%) rename docs/{reference/cli => operate/cli/reference}/postgres.md (99%) rename docs/{reference/cli => operate/cli/reference}/validate.md (92%) create mode 100644 docs/operate/console.md rename docs/{how-to-guides/command-line-access/setup.md => operate/how-to/command-line-access.md} (63%) rename docs/{how-to-guides/team.md => operate/how-to/create-team.md} (61%) create mode 100644 docs/operate/naisdevice/.pages create mode 100644 docs/operate/naisdevice/README.md rename {tenants/nav/how-to-guides/naisdevice => docs/operate/naisdevice/how-to}/install.md (52%) rename docs/{how-to-guides/naisdevice => operate/naisdevice/how-to}/troubleshooting.md (91%) create mode 100644 docs/operate/naisdevice/how-to/uninstall.md rename docs/{how-to-guides/naisdevice => operate/naisdevice/how-to}/update.md (94%) create mode 100644 docs/persistence/.pages create mode 100644 docs/persistence/README.md create mode 100644 docs/persistence/bigquery/.pages rename docs/{explanation/database/bigquery.md => persistence/bigquery/README.md} (78%) rename docs/{how-to-guides/persistence/bigquery => persistence/bigquery/how-to}/connect.md (92%) rename docs/{how-to-guides/persistence/bigquery => persistence/bigquery/how-to}/create.md (76%) create mode 100644 docs/persistence/buckets/.pages create mode 100644 docs/persistence/buckets/README.md rename docs/{how-to-guides/persistence/buckets => persistence/buckets/how-to}/create.md (61%) rename docs/{how-to-guides/persistence/buckets => persistence/buckets/how-to}/delete.md (89%) rename docs/{reference/bucket-backup.md => persistence/buckets/reference.md} (91%) create mode 100644 docs/persistence/explanations/responsibilities.md create mode 100644 docs/persistence/kafka/.pages rename docs/{explanation/kafka.md => persistence/kafka/README.md} (89%) rename docs/{how-to-guides/persistence/kafka => persistence/kafka/how-to}/access.md (69%) rename docs/{how-to-guides/persistence/kafka => persistence/kafka/how-to}/create.md (71%) rename docs/{how-to-guides/persistence/kafka => persistence/kafka/how-to}/delete.md (85%) rename docs/{how-to-guides/persistence/kafka => persistence/kafka/how-to}/internal.md (82%) rename docs/{how-to-guides/persistence/kafka => persistence/kafka/how-to}/manage-acl.md (85%) rename docs/{how-to-guides/persistence/kafka => persistence/kafka/how-to}/monitoring.md (98%) rename docs/{how-to-guides/persistence/kafka => persistence/kafka/how-to}/remove-access.md (78%) rename docs/{how-to-guides/persistence/kafka => persistence/kafka/how-to}/schema-operations.md (98%) rename docs/{reference/kafka.md => persistence/kafka/reference/environment-variables.md} (56%) rename docs/{ => persistence/kafka}/reference/kafka-topic-example.md (100%) rename docs/{ => persistence/kafka}/reference/kafka-topic-spec.md (100%) create mode 100644 docs/persistence/opensearch/.pages rename docs/{how-to-guides => }/persistence/opensearch/README.md (64%) rename docs/{how-to-guides/persistence/opensearch => persistence/opensearch/how-to}/create.md (90%) rename docs/{reference/opensearch.md => persistence/opensearch/reference.md} (88%) rename docs/{how-to-guides => }/persistence/postgres/README.md (89%) create mode 100644 docs/persistence/redis/.pages create mode 100644 docs/persistence/redis/README.md rename docs/{how-to-guides/persistence/redis/README.md => persistence/redis/how-to/create-application.md} (68%) rename docs/{how-to-guides/persistence/redis/create-redis-instance-explicitly.md => persistence/redis/how-to/create-explicit.md} (94%) rename docs/{reference/redis.md => persistence/redis/reference.md} (78%) delete mode 100644 docs/reference/README.md delete mode 100644 docs/reference/access-policy.md delete mode 100644 docs/reference/cli/.pages delete mode 100644 docs/reference/default-variables.md delete mode 100644 docs/reference/deploy-action-config.md delete mode 100644 docs/reference/environments.md delete mode 100644 docs/reference/kyverno-policies.md delete mode 100644 docs/reference/secrets.md delete mode 100644 docs/reference/service-discovery.md create mode 100644 docs/services/.pages create mode 100644 docs/services/README.md rename docs/{security => services}/antivirus.md (96%) create mode 100644 docs/services/cdn/.pages rename docs/{explanation/cdn.md => services/cdn/README.md} (94%) rename docs/{how-to-guides/cdn.md => services/cdn/how-to/upload-assets.md} (84%) rename docs/{reference/cdn.md => services/cdn/reference.md} (90%) rename docs/{explanation => services}/feature-toggling.md (99%) create mode 100644 docs/services/leader-election/.pages rename docs/{explanation/leader-election.md => services/leader-election/README.md} (89%) rename docs/{how-to-guides/leader-election.md => services/leader-election/how-to/enable.md} (82%) rename docs/{security/salsa/README.md => services/salsa.md} (98%) create mode 100644 docs/services/secrets/.pages rename docs/{explanation/secrets.md => services/secrets/README.md} (75%) rename docs/{how-to-guides/secrets => services/secrets/how-to}/console.md (88%) rename docs/{how-to-guides/secrets => services/secrets/how-to}/workload.md (88%) create mode 100644 docs/services/secrets/reference.md rename docs/{reference => }/tags.md (100%) delete mode 100644 docs/tutorial/.pages delete mode 100644 docs/tutorial/README.md delete mode 100644 docs/tutorial/hello-nais/hello-nais-1.md delete mode 100644 docs/tutorial/hello-nais/hello-nais-2.md delete mode 100644 docs/tutorial/hello-nais/hello-nais-3.md delete mode 100644 docs/tutorial/hello-nais/hello-nais-4.md create mode 100644 docs/tutorials/.pages create mode 100644 docs/tutorials/README.md create mode 100644 docs/tutorials/hello-nais.md create mode 100644 docs/workloads/.pages create mode 100644 docs/workloads/README.md create mode 100644 docs/workloads/application/.pages create mode 100644 docs/workloads/application/README.md rename docs/{explanation/exposing-application.md => workloads/application/explanations/expose.md} (68%) create mode 100644 docs/workloads/application/how-to/create.md create mode 100644 docs/workloads/application/how-to/delete.md create mode 100644 docs/workloads/application/how-to/expose.md rename docs/{ => workloads/application}/reference/application-example.md (98%) rename docs/{ => workloads/application}/reference/application-spec.md (99%) create mode 100644 docs/workloads/application/reference/automatic-scaling.md rename docs/{explanation => workloads/explanations}/environment.md (53%) rename docs/{explanation => workloads/explanations}/good-practices.md (94%) create mode 100644 docs/workloads/explanations/zero-trust.md rename docs/{how-to-guides => workloads/how-to}/access-policies.md (92%) create mode 100644 docs/workloads/how-to/communication.md create mode 100644 docs/workloads/job/.pages create mode 100644 docs/workloads/job/README.md create mode 100644 docs/workloads/job/how-to/create.md create mode 100644 docs/workloads/job/how-to/delete.md rename docs/{ => workloads/job}/reference/naisjob-example.md (99%) rename docs/{ => workloads/job}/reference/naisjob-spec.md (100%) create mode 100644 docs/workloads/reference/access-policies.md create mode 100644 docs/workloads/reference/default-variables.md create mode 100644 docs/workloads/reference/environments.md rename docs/{ => workloads}/reference/ingress.md (70%) rename docs/{ => workloads}/reference/json-schema.md (98%) rename tenants/nav/{how-to-guides => build/how-to}/oci-migration.md (90%) delete mode 100644 tenants/nav/explanation/migrating-databases-to-gcp.md delete mode 100644 tenants/nav/explanation/migrating-to-gcp.md delete mode 100644 tenants/nav/explanation/naisdevice.md delete mode 100644 tenants/nav/how-to-guides/persistence/influxdb/datasource.md rename tenants/nav/{reference => }/legal/app-pvk.md (57%) rename tenants/nav/{reference => }/legal/app-ros.md (100%) rename tenants/nav/{reference => }/legal/arkivloven.md (100%) rename tenants/nav/{reference => }/legal/dpa/README.md (100%) rename tenants/nav/{reference => }/legal/dpa/aiven-dpa.md (78%) rename tenants/nav/{reference => }/legal/dpa/azure-dpa.md (100%) rename tenants/nav/{reference => }/legal/dpa/gcp-dpa.md (100%) rename tenants/nav/{reference => }/legal/nais-pvk.md (95%) rename tenants/nav/{reference => }/legal/nais-ros.md (100%) rename tenants/nav/{reference => }/legal/roles-responsibilities.md (100%) rename tenants/nav/{how-to-guides/observability/logs => observability/logging/how-to}/access-secure-logs.md (83%) rename tenants/nav/{how-to-guides/observability/logs => observability/logging/how-to}/audit-logs.md (91%) rename tenants/nav/{how-to-guides/observability/logs => observability/logging/how-to}/enable-secure-logs.md (94%) rename tenants/nav/{how-to-guides/observability/logs => observability/logging/how-to}/kibana.md (84%) rename tenants/nav/{reference/observability/logs => observability/logging/reference}/kql.md (98%) rename tenants/nav/{how-to-guides/observability/metrics => observability/metrics/how-to}/grafana-from-infoscreen.md (98%) rename tenants/nav/{reference/cli => operate/cli/reference}/aiven.md (88%) rename tenants/nav/{reference/cli => operate/cli/reference}/device.md (87%) create mode 100644 tenants/nav/operate/naisdevice/.pages rename tenants/nav/{reference/naisdevice => operate/naisdevice/explanations}/jita.md (71%) rename tenants/nav/{how-to-guides/naisdevice => operate/naisdevice/how-to}/install-kolide.md (98%) rename tenants/nav/{how-to-guides/naisdevice => operate/naisdevice/how-to}/troubleshooting.md (93%) rename tenants/nav/{how-to-guides/naisdevice => operate/naisdevice/how-to}/uninstall-kolide.md (97%) create mode 100644 tenants/nav/persistence/influxdb/.pages create mode 100644 tenants/nav/persistence/influxdb/README.md rename tenants/nav/{how-to-guides/persistence/influxdb => persistence/influxdb/how-to}/access.md (83%) rename tenants/nav/{how-to-guides/persistence/influxdb => persistence/influxdb/how-to}/create.md (62%) create mode 100644 tenants/nav/persistence/influxdb/reference.md rename tenants/nav/{how-to-guides/persistence/kafka => persistence/kafka/how-to}/access-from-non-nais.md (80%) rename tenants/nav/{how-to-guides/persistence/kafka => persistence/kafka/how-to}/renew-credentials-for-non-nais.md (90%) create mode 100644 tenants/nav/persistence/postgres/.pages rename tenants/nav/{how-to-guides/persistence => persistence/postgres/how-to}/migrating-databases-to-gcp.md (97%) delete mode 100644 tenants/nav/reference/environments.md create mode 100644 tenants/nav/workloads/explanations/migrating-to-gcp.md delete mode 100644 tenants/ssb/reference/environments.md diff --git a/build.sh b/build.sh index d8b8b1a5..568285e6 100755 --- a/build.sh +++ b/build.sh @@ -1,4 +1,5 @@ #! /bin/bash +set -e rm -rf ./out ./docs-base mkdir -p ./out ./docs-base @@ -10,6 +11,7 @@ for TENANT in $@; do rm -rf ./docs cp -r ./docs-base ./docs - cp -rf ./tenants/$TENANT/* ./docs + cp -rf ./tenants/$TENANT/* ./docs || true TENANT=$TENANT poetry run mkdocs build --strict -d out/$TENANT done + diff --git a/docs/.pages b/docs/.pages new file mode 100644 index 00000000..4aef0b14 --- /dev/null +++ b/docs/.pages @@ -0,0 +1,17 @@ +nav: + - "": + - explanations + - tutorials + - "": + - workloads + - build + - authentication + - observability + - persistence + - security + - Other services: services + - "": + - operate + - "": + - tags.md + - ... diff --git a/docs/README.md b/docs/README.md index c12051e0..cd85ba47 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,57 +2,46 @@ hide: - feedback - footer + - toc --- - - -# NAIS Documentation +# :wave: **Welcome to the NAIS developer documentation!** -
-- :seedling: **Getting Started?** +Here you'll find _explanations_[^1], _how-to guides_[^2], and _references_[^3] for all things NAIS. - --- - - Initially it's a good idea to learn about [what NAIS is](./explanation/nais.md) to get an idea of the fundamentals. - - Once you're familiar with the basic concepts, move on to the [Hello NAIS](./tutorial/hello-nais/hello-nais-1.md) tutorial to get your first app running. +### :seedling: **New to NAIS?** -
+Start here to get an idea of the fundamentals.
-- :rocket: **Tutorials** - - --- - - Learning-oriented lessons that take you through a series of steps to complete a project. Most useful when you want to get started with NAIS. - - [:octicons-arrow-right-24: Tutorials](tutorial/README.md) - -- :dart: **How-to guides** - - --- - Practical step-by-step guides to help you achieve a specific goal. Most useful when you're trying to get something done. +- :ok_hand: [**What is NAIS?**](explanations/nais.md) +- :student: [**Your first application; Hello NAIS**](tutorials/hello-nais.md) - [:octicons-arrow-right-24: How-to guides](how-to-guides/README.md) - -- :bulb: **Explanation** - - --- - - Big-picture explanations of higher-level concepts. Most useful when you want to understand how NAIS works. - - [:octicons-arrow-right-24: Explanations](explanation/README.md) +
-- :books: **Reference** +### :technologist: **Already familiar with NAIS?** - --- +What can we help you with today? - Reference documentation for the NAIS platform. Most useful when you need to look up details about a specific feature. +
- [:octicons-arrow-right-24: Reference](reference/README.md) +- :package: [**Run your code**](workloads/README.md) +- :rocket: [**Build and deploy your code**](build/README.md) +- :open_file_folder: [**Store your data**](persistence/README.md) +- :closed_lock_with_key: [**Authenticate your users**](security/auth/README.md) +- :telescope: [**Gain insight into your workloads**](observability/README.md) +- :wrench: [**Manage your workloads and services**](operate/README.md) +- :heavy_plus_sign: [**Explore the rest of NAIS**](services/README.md)
+ +[^1]: an :bulb: [_explanation_](tags.md#explanation) presents higher-level concepts. Most useful when you want to understand how NAIS works. +[^2]: a :dart: [_how-to guide_](tags.md#how-to) helps you achieve a specific goal. Most useful when you're trying to get something done. +[^3]: a :books: [_reference_](tags.md#reference) contains technical descriptions and specifications. Most useful when you need to look up details about a specific feature. diff --git a/docs/authentication/.pages b/docs/authentication/.pages new file mode 100644 index 00000000..e2d5ae91 --- /dev/null +++ b/docs/authentication/.pages @@ -0,0 +1 @@ +hide: true diff --git a/docs/authentication/machines/README.md b/docs/authentication/machines/README.md new file mode 100644 index 00000000..2eee922c --- /dev/null +++ b/docs/authentication/machines/README.md @@ -0,0 +1 @@ +# Machines \ No newline at end of file diff --git a/docs/authentication/users/README.md b/docs/authentication/users/README.md new file mode 100644 index 00000000..fd2db7ac --- /dev/null +++ b/docs/authentication/users/README.md @@ -0,0 +1 @@ +# Users \ No newline at end of file diff --git a/docs/build/.pages b/docs/build/.pages new file mode 100644 index 00000000..c30c7a0d --- /dev/null +++ b/docs/build/.pages @@ -0,0 +1,5 @@ +title: Build and deploy +nav: +- README.md +- 🎯 How-To: how-to +- ... diff --git a/docs/build/README.md b/docs/build/README.md new file mode 100644 index 00000000..e846b409 --- /dev/null +++ b/docs/build/README.md @@ -0,0 +1,25 @@ +--- +tags: [build, deploy, explanation, services] +--- + +# Build and deploy + +To make your application available to others, you need to build and deploy it. + +NAIS attempts to make this as simple as possible by providing a set of composable [GitHub Actions](https://docs.github.com/en/actions). + +Use these actions to compose your own build and deploy pipeline through [Github Actions workflows](https://docs.github.com/en/actions/using-workflows). + +## GitHub Actions + +:books: [nais/docker-build-push](https://github.com/nais/docker-build-push) + +:books: [nais/deploy](https://github.com/nais/deploy/tree/master/actions/deploy) + +See the respective GitHub Action links for detailed configuration options. + +## What's next + +:dart: [Build and deploy with Github Actions](how-to/build-and-deploy.md) + +:dart: [Set up auto-merge with Dependabot](how-to/dependabot-auto-merge.md) diff --git a/docs/how-to-guides/github-action.md b/docs/build/how-to/build-and-deploy.md similarity index 86% rename from docs/how-to-guides/github-action.md rename to docs/build/how-to/build-and-deploy.md index caa5cab6..ff395a10 100644 --- a/docs/how-to-guides/github-action.md +++ b/docs/build/how-to/build-and-deploy.md @@ -1,16 +1,20 @@ +--- +tags: [build, deploy, how-to] +--- + # Build and deploy with Github Actions This how-to guide shows you how to build and deploy your application using [Github Actions](https://help.github.com/en/actions/automating-your-workflow-with-github-actions) and the NAIS deploy action. ## Prerequisites -- You're part of a [NAIS team](./team.md) +- You're part of a [NAIS team](../../operate/how-to/create-team.md) - A Github repository where the NAIS team has access -- The repository contains a valid [workload manifest](../explanation/workloads/README.md) +- The repository contains a valid [workload manifest](../../workloads/README.md) ## Authorize your Github repository for deployment -1. Open [NAIS console](https://console.<>.cloud.nais.io) in your browser and select your team. +1. Open [NAIS Console](https://console.<>.cloud.nais.io) in your browser and select your team. 2. Select the `Repositories` tab 3. Find the repository you want to deploy from, and click `Authorize` @@ -52,7 +56,7 @@ This how-to guide shows you how to build and deploy your application using [Gith ``` This example workflow is a minimal example that builds, signs, and pushes your container image to the image registry. -It then deploys the [app.yaml](../reference/application-spec.md), injecting the image tag from the previous step. +It then deploys the [app.yaml](../../workloads/application/reference/application-spec.md), injecting the image tag from the previous step. When this file is pushed to the `main` branch, the workflow will be triggered and you are all set. diff --git a/docs/how-to-guides/dependabot-auto-merge.md b/docs/build/how-to/dependabot-auto-merge.md similarity index 99% rename from docs/how-to-guides/dependabot-auto-merge.md rename to docs/build/how-to/dependabot-auto-merge.md index 05c4d107..6587331f 100644 --- a/docs/how-to-guides/dependabot-auto-merge.md +++ b/docs/build/how-to/dependabot-auto-merge.md @@ -1,3 +1,7 @@ +--- +tags: [build, deploy, how-to] +--- + # Dependabot with auto-merge [working-with-dependabot]: https://docs.github.com/en/code-security/dependabot/working-with-dependabot diff --git a/docs/explanation/.pages b/docs/explanation/.pages deleted file mode 100644 index a11838b1..00000000 --- a/docs/explanation/.pages +++ /dev/null @@ -1,9 +0,0 @@ -title: Explanations -nav: - - nais.md - - team.md - - workloads - - zero-trust.md - - under-the-hood.md - - naisdevice.md - - ... diff --git a/docs/explanation/README.md b/docs/explanation/README.md deleted file mode 100644 index 87a7e4c7..00000000 --- a/docs/explanation/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# Explanations - -Big picture explanations of higher-level concepts. Most useful when you want to understand how NAIS works. diff --git a/docs/explanation/database/opensearch.md b/docs/explanation/database/opensearch.md deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/explanation/naisdevice.md b/docs/explanation/naisdevice.md deleted file mode 100644 index c3b5f223..00000000 --- a/docs/explanation/naisdevice.md +++ /dev/null @@ -1,9 +0,0 @@ -# Naisdevice - -Naisdevice is a mechanism provided by NAIS, that lets you connect to services not available on the public Internet from your machine. - -Examples of such services are: - -- Access to the NAIS cluster with kubectl -- Applications on internal domains -- Internal NAIS services such as [console](https://console.<>.cloud.nais.io). diff --git a/docs/explanation/restoring.md b/docs/explanation/restoring.md deleted file mode 100644 index 156ff1e2..00000000 --- a/docs/explanation/restoring.md +++ /dev/null @@ -1,5 +0,0 @@ -# Restoring resources - -Every second hour, we backup of all the workload and resource definitions in the environments. - -If you mess up something in your namespace and need something restored, contact the NAIS team on Slack and we will help you out. diff --git a/docs/explanation/team.md b/docs/explanation/team.md deleted file mode 100644 index 2a4d32ed..00000000 --- a/docs/explanation/team.md +++ /dev/null @@ -1,20 +0,0 @@ -# What is a team? - -Everything in NAIS is organized around the concept of a team. -Nothing in NAIS is owned by an individual; the team as a whole owns the [workloads](./workloads/README.md) built by the team, as well as all provisioned resources. This is to ensure that everything can continue to operate even if someone leaves. - -A NAIS team doesn't necessarily map directly to the organizational team unit, and (usually) consists of purely technical personnel developing and operating on the same set of products or services. The reason for this is that being member of a NAIS team will grant you access to all the workloads and provisioned resources that the team owns. To reduce the attack surface, it's a good idea to limit access to the people that actually need it. - -## The anatomy of a team - -A team has two different roles, `owner` and `member`. -A team has at least one `owner`, and can have multiple `members`. The `owners` have permission to add and remove `members`, as well as changing the roles of the `members`. -You can be a member and owner of multiple teams. - -## What does a NAIS team provide? - -When you [create a team](../how-to-guides/team.md), the following will be provisioned for you: - -- An isolated area for your team's workload and resources in each environment (e.g. dev and prod) -- A GitHub team with the same name in your GitHub organization. The members of your NAIS team will be synchronized with the GitHub team. -- Roles and permissions to access the teams workloads and resources. diff --git a/docs/explanation/under-the-hood.md b/docs/explanation/under-the-hood.md deleted file mode 100644 index a2ab72b0..00000000 --- a/docs/explanation/under-the-hood.md +++ /dev/null @@ -1,54 +0,0 @@ -# Under the hood -In this explanation, we will go through some of the underlying technologies we use to provide NAIS. - -## Environment - -### Runtime implementation -Each environment is its own [Kubernetes](https://kubernetes.io) cluster using [GKE](https://cloud.google.com/kubernetes-engine?hl=en). -Inside each environment, every team has their own [namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/), which is only accessible by the members of the team. - -### Workload isolation -All workloads are deployed in a team namespace and every workload is isolated from _all_ other workloads by utilizing [Kubernetes network policies](https://kubernetes.io/docs/concepts/services-networking/network-policies/) unless [explicitly allowed](./zero-trust.md). - -## GCP resources (CloudSQL, Cloud Storage, BigQuery, etc.) -When resources, such as a database, is requested, it is provisioned in a separate GCP project that is dedicated to _this_ team for _this_ environment. -As with the team's namespace, the team's project is only accessible by the members of the team. - -Example NAIS environment: -```mermaid -graph LR -subgraph GCP - subgraph NAIS-dev cluster - subgraph team-a-ns[Team A namespace] - team-a-app[App A] - end - - subgraph team-b-ns[Team B namespace] - team-b-app[App B] - end - - subgraph team-c-ns[Team C namespace] - team-c-app[App C] - end - end - - subgraph team-a-project[A-dev project] - team-a-db[Database A] - end - - subgraph team-b-project[B-dev project] - team-b-db[Database B] - end - - subgraph team-c-project[C-dev project] - team-c-db[Database C] - end -end - -team-a-app --> team-a-db -team-b-app --> team-b-db -team-c-app --> team-c-db -``` - -In the example above, we have three teams, `A`, `B` and `C`. -Each team has their own namespace in the `dev` cluster, and when they request a database, it is provisioned in their own `team-dev` project. \ No newline at end of file diff --git a/docs/explanation/workloads/README.md b/docs/explanation/workloads/README.md deleted file mode 100644 index 68149844..00000000 --- a/docs/explanation/workloads/README.md +++ /dev/null @@ -1,11 +0,0 @@ -# Workloads - -The main purpose of NAIS is enabling the developer to run the code they write. - -Below is a list of the different kinds we support. - -## NAIS application -A [NAIS application](./application.md) is a used for long-running processes such as a API. - -## NAIS job -A [NAIS job](./job.md) is used for tasks meant to complete and then exit. This can either run as a one-off task or on a schedule. diff --git a/docs/explanation/workloads/application.md b/docs/explanation/workloads/application.md deleted file mode 100644 index c4c5b19e..00000000 --- a/docs/explanation/workloads/application.md +++ /dev/null @@ -1,11 +0,0 @@ -# Application - -!!! warning - This explanation is incomplete - -A [NAIS application](../../reference/application-example.md) lets you run one or more instances of a container image. - -An application is defined by its [application manifest](../../reference/application-spec.md), which is a YAML file that describes how the application should be run and what resources it needs. - -Once the application manifest is applied, NAIS will set up your application as specified. If you've requested resources, NAIS will provision and configure your application to use those resources. - diff --git a/docs/explanation/workloads/job.md b/docs/explanation/workloads/job.md deleted file mode 100644 index 4ce53a3a..00000000 --- a/docs/explanation/workloads/job.md +++ /dev/null @@ -1,7 +0,0 @@ -# NAIS Job - -!!! warning - This explanation is incomplete - -A NAIS Job is used for tasks meant to complete and then exit. This can either run as a one-off task or on a schedule, like a [cron job](https://en.wikipedia.org/wiki/Cron). - diff --git a/docs/explanation/zero-trust.md b/docs/explanation/zero-trust.md deleted file mode 100644 index fbe9c7b1..00000000 --- a/docs/explanation/zero-trust.md +++ /dev/null @@ -1,42 +0,0 @@ -# Zero trust - -NAIS embraces the [zero trust](https://en.wikipedia.org/wiki/Zero_trust_security_model) security model, where the core principle is to "never trust, always verify". - -In NAIS every [workload](./workloads/README.md) is isolated by default - which means that it is not able to make _any_ outbound requests or receive _any_ incoming traffic unless explicitly defined. This includes traffic inside your namespace, in the same environment as well as to and from the Internet. -In order to control traffic to and from your workload, you need to define [access policies](../how-to-guides/access-policies.md). - -For the native NAIS services - the platform takes care of this for you. For example, when you have a [database](../how-to-guides/persistence/postgres/README.md), the access policies required to reach the database will be created automatically. - -## Example - -Consider a simple application which consists of a frontend and a backend, where naturally the frontend needs to communicate with the backend. - -This communication is denied by default as indicated by the red arrow. -![access-policy-1](../assets/access-policy-1.png) - -In order to fix this, the frontend needs to allow outbound traffic to the backend by adding the following access policy. - -```yaml -spec: - accessPolicy: - outbound: - - application: backend -``` - -![access-policy-2](../assets/access-policy-2.png) - -However - the frontend is still not allowed to make any requests to the backend. -The missing piece of the puzzle is adding an inbound policy to the backend like so: - -```yaml -spec: - accessPolicy: - inbound: - - application: frontend -``` - -![access-policy-3](../assets/access-policy-3.png) - -Now that both applications has explicitly declared their policies, the communication is allowed. - -See more about [how to define access policies](../how-to-guides/access-policies.md) diff --git a/docs/explanations/.pages b/docs/explanations/.pages new file mode 100644 index 00000000..64d37113 --- /dev/null +++ b/docs/explanations/.pages @@ -0,0 +1,4 @@ +nav: +- nais.md +- team.md +- under-the-hood.md diff --git a/docs/explanation/nais.md b/docs/explanations/nais.md similarity index 93% rename from docs/explanation/nais.md rename to docs/explanations/nais.md index d57f322a..89e5a2bf 100644 --- a/docs/explanation/nais.md +++ b/docs/explanations/nais.md @@ -1,3 +1,7 @@ +--- +tags: [explanation, nais] +--- + # What is NAIS? NAIS is a platform aiming to provide you with the technical capabilities you need to develop and run software in a safe and enjoyable way. @@ -8,7 +12,7 @@ In order to support this idea, we aim to provide you with functionality that jus You can think of the provided functionality as building blocks, where you as a developer can select the ones that fit your specific needs. -The fundamental building block provided by NAIS is a robust and secure runtime environment for your [workloads](./workloads/README.md). +The fundamental building block provided by NAIS is a robust and secure runtime environment for your [workloads](../workloads/README.md). When your workload is up and running, it’s crucial to be able to observe how it’s doing. Here the platform provides you with the tooling you need to log, emit metrics and run traces. diff --git a/docs/explanations/team.md b/docs/explanations/team.md new file mode 100644 index 00000000..72cb568a --- /dev/null +++ b/docs/explanations/team.md @@ -0,0 +1,30 @@ +--- +tags: [explanation, nais, team] +--- + +# What is a team? + +Everything in NAIS is organized around the concept of a _team_. + +A NAIS team should consist of technical personnel involved with developing and operating the team's workloads and resources. + +Being member of a team grants you full access to the team's workloads and provisioned resources. +Limit access to the people that actually need it according to the _principle of least privilege_. + +## The anatomy of a team + +A team consists of one or more _users_. The team has at least one `owner` and can have multiple `members`. + +An `owner` can add, remove, and change the roles of other users on the team. + +A user can be part of multiple teams. + +## What happens when you create a team? + +When you [create a team](../operate/how-to/create-team.md), the following will be provisioned for you: + +- An isolated area for your team's workloads and resources in each environment (e.g. `dev` and `prod`) +- A GitHub team with the same name in your GitHub organization. The members of your NAIS team will be synchronized with the GitHub team. +- Roles and permissions to access the teams workloads and resources. + +The creator of a team is automatically granted `owner` privileges for the team. diff --git a/docs/explanations/under-the-hood.md b/docs/explanations/under-the-hood.md new file mode 100644 index 00000000..23a1e25b --- /dev/null +++ b/docs/explanations/under-the-hood.md @@ -0,0 +1,75 @@ +--- +tags: [explanation, nais] +--- + +# Under the hood + +In this explanation, we will go through some of the underlying technologies we use to provide NAIS. + +## Environment + +### Runtime implementation + +Each _environment_ is its own [Kubernetes :octicons-link-external-16:](https://kubernetes.io) cluster using [Google Kubernetes Engine (GKE) :octicons-link-external-16:](https://cloud.google.com/kubernetes-engine?hl=en). + +Inside each environment, every team has their own [namespace :octicons-link-external-16:](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/). + +A namespace can contain one or more [workloads](../workloads/README.md). +Only members of the team have access to the namespace and its resources. + +```mermaid +graph LR + subgraph env-dev[dev environment] + subgraph ns-dev[team namespace] + app[App] + job[Job] + end + end +``` + +In the example above, the team has an application and a job running in the `dev` environment. + +### Workload isolation + +All workloads are deployed in a team namespace. + +Every workload is isolated from _all_ other workloads with [Kubernetes network policies :octicons-link-external-16:](https://kubernetes.io/docs/concepts/services-networking/network-policies/). + +Access is denied by default, unless [explicitly allowed](../workloads/explanations/zero-trust.md). + +## Google Cloud Platform (GCP) resources + +Each team has a dedicated [GCP project :octicons-link-external-16:](https://cloud.google.com/resource-manager/docs/creating-managing-projects) for _each_ environment. + +When your workload requests resources e.g. a bucket, it will be provisioned in the team's project for the matching environment. + +```mermaid +graph LR + subgraph env-dev["dev environment"] + subgraph ns-dev[team namespace] + app-dev[App] + end + end + + subgraph project-dev[team project dev] + bucket-dev[Bucket] + end + + subgraph env-prod["prod environment"] + subgraph ns-prod[team namespace] + app-prod[App] + end + end + + subgraph project-prod[team project prod] + bucket-prod[Bucket] + end + +app-dev--> bucket-dev +app-prod--> bucket-prod +``` + +In the example above, the team has an application running in the `dev` environment. +When the application requests a bucket, it is provisioned in the team's `dev` project. + +Equivalently for the `prod` environment, the bucket is provisioned in the team's `prod` project. diff --git a/docs/how-to-guides/.pages b/docs/how-to-guides/.pages deleted file mode 100644 index 74f970ed..00000000 --- a/docs/how-to-guides/.pages +++ /dev/null @@ -1 +0,0 @@ -title: How-to guides diff --git a/docs/how-to-guides/README.md b/docs/how-to-guides/README.md deleted file mode 100644 index 3294dfc7..00000000 --- a/docs/how-to-guides/README.md +++ /dev/null @@ -1,4 +0,0 @@ -# How-to guides - -Practical step-by-step guides to help you achieve a specific goal. Most useful when you're trying to get something done. - diff --git a/docs/how-to-guides/command-line-access/.pages b/docs/how-to-guides/command-line-access/.pages deleted file mode 100644 index 2a783581..00000000 --- a/docs/how-to-guides/command-line-access/.pages +++ /dev/null @@ -1 +0,0 @@ -title: Command line access diff --git a/docs/how-to-guides/command-line-access/troubleshooting.md b/docs/how-to-guides/command-line-access/troubleshooting.md deleted file mode 100644 index abee3b46..00000000 --- a/docs/how-to-guides/command-line-access/troubleshooting.md +++ /dev/null @@ -1,8 +0,0 @@ -## Troubleshooting - -## Mac: GCP auth plugin has been removed -If you get `error: The gcp auth plugin has been removed` after you have updated the kubeconfig, you might be missing kubelogin. - -Run ```which kubelogin``` in a terminal - -Install kubelogin if the output is empty, (Follow the instructions in [kubelogins documentation](https://azure.github.io/kubelogin/install.html)) \ No newline at end of file diff --git a/docs/how-to-guides/communicating-inside-environment.md b/docs/how-to-guides/communicating-inside-environment.md deleted file mode 100644 index 3c6f945d..00000000 --- a/docs/how-to-guides/communicating-inside-environment.md +++ /dev/null @@ -1,24 +0,0 @@ -# Communicating inside the environment - -This guide will show you how to communicate with other applications inside the same environment. - -## Prerequisites -- Working [access policies](./access-policies.md) for the applications you want to communicate with. - -## Identify the endpoint you want to communicate with - -To identity the endpoint of the workload we are communicating with, we need to know it's `name` and what `namespace` it's running in. - -If the workload you are calling is in the same namespace, you can reach it by calling it's name directly using HTTP like so: - -```plaintext -http:// -``` - -If the workload is running in another team's namespace, you need to specify the namespace as well: - -```plaintext -http://. -``` - -With this endpoint, you can now call the workload using HTTP from your own workload. diff --git a/docs/how-to-guides/exposing-an-application.md b/docs/how-to-guides/exposing-an-application.md deleted file mode 100644 index 3599ce46..00000000 --- a/docs/how-to-guides/exposing-an-application.md +++ /dev/null @@ -1,26 +0,0 @@ -# Expose your application - -This guide will show you how to [expose your application to the correct audience](../explanation/exposing-application.md). - -## Select audience - -Select the correct audience from the available [domains in your environment](../reference/environments.md). - -## Define ingress - -Specify the desired hostname for your application in the [application manifest](../reference/application-spec.md#ingresses). -???+ note ".nais/app.yaml" - - ```yaml hl_lines="4-5" - apiVersion: nais.io/v1alpha1 - kind: Application - spec: - ingresses: - - https://. - ``` - -!!! tip "Specific paths" - - You can optionally specify a path for each individual ingress to only expose a subset of your application. - - diff --git a/docs/how-to-guides/nais-cli/.pages b/docs/how-to-guides/nais-cli/.pages deleted file mode 100644 index f987054a..00000000 --- a/docs/how-to-guides/nais-cli/.pages +++ /dev/null @@ -1 +0,0 @@ -title: NAIS CLI diff --git a/docs/how-to-guides/naisdevice/.pages b/docs/how-to-guides/naisdevice/.pages deleted file mode 100644 index 0dc4264a..00000000 --- a/docs/how-to-guides/naisdevice/.pages +++ /dev/null @@ -1 +0,0 @@ -title: naisdevice diff --git a/docs/how-to-guides/naisdevice/install.md b/docs/how-to-guides/naisdevice/install.md deleted file mode 100644 index 50331223..00000000 --- a/docs/how-to-guides/naisdevice/install.md +++ /dev/null @@ -1,102 +0,0 @@ -# Install - -## Device-specific installation steps - -=== "macOS" - - 1. [Install Homebrew](https://brew.sh/) unless you already have it. - - Homebrew makes it possible to install and maintain apps using the terminal app on your Mac. - - 1. Open terminal (Use ` + ` to find `Terminal.app`) and add the nais tap by typing or pasting the text below and press ``. - - Adding the nais tap lets Homebrew know where to get and update files from. Do not worry about where it will be installed, we got you covered. - - ```bash - brew tap nais/tap - ``` - - 1. When the tap is added, you are ready to install naisdevice, by typing or pasting the following in terminal and press ``. - - ```bash - brew install naisdevice-tenant - ``` - - 1. You will be asked for your local device account's password to finish the installation. - - 1. Turn on your freshly installed `naisdevice` app. - - 1. Use ` + ` to find your `naisdevice.app` and press ``. - 1. Follow the [instructions to connect your _nais_ device](#connect-naisdevice-through-tasksys-tray-icon). - -=== "Windows" - - #### Install using Scoop - - 1. Install [Scoop](https://scoop.sh) unless you already have it. - - Scoop makes it possible to install and maintain programs from the command line. - - 1. Use the following command in the command line to add the nais bucket to let Scoop know where to get and update files from. Do not worry about where it will be installed, we got you covered. - - ```powershell - scoop bucket add nais https://github.com/nais/scoop-bucket - ``` - - 1. When the bucket is added, you are ready to install naisdevice, by typing the following in the command line: - - ```powershell - scoop install naisdevice-tenant - ``` - - (you will be asked for administrator access to run the installer) - 1. Start _naisdevice_ from the _Start menu_ - -=== "Manual" - - 1. [Download and install naisdevice-tenant.exe](https://github.com/nais/device/releases/latest) - (you will be asked for administrator access when you run the installer) - 1. Start _naisdevice_ from the _Start menu_ - -=== "Ubuntu" - - !!! warning - - Using Gnome DE on latest Ubuntu LTS - only supported variant atm - - 1. Add the nais PPA repo: - - ``` - NAIS_GPG_KEY="/etc/apt/keyrings/nav_nais_gar.asc" - curl -sfSL "https://europe-north1-apt.pkg.dev/doc/repo-signing-key.gpg" | sudo dd of="$NAIS_GPG_KEY" - echo "deb [arch=amd64 signed-by=$NAIS_GPG_KEY] https://europe-north1-apt.pkg.dev/projects/nais-io nais-ppa main" | sudo tee /etc/apt/sources.list.d/nav_nais_gar.list - sudo apt update - ``` - - **NOTE** curl is not installed in a "fresh" ubuntu: - - ``` - sudo apt install curl - ``` - - 1. Install the naisdevice package: - - ``` - sudo apt install naisdevice-tenant - ``` - - 1. Turn on your freshly installed `naisdevice` application. - 1. Find `naisdevice` in your application menu, or use the `naisdevice` command in a terminal to start the application. - 2. Follow the [instructions to connect your _nais_ device](#connect-naisdevice-through-tasksys-tray-icon). - - ### Connect naisdevice through task/sys -tray icon - - ![A macOS systray exemplifying a red-colored `naisdevice` icon.](../../assets/naisdevice-systray-icon.svg) - - When you have opened naisdevice, you may be concerned that nothing happened. The little naisdevice icon has appeared in your Systray (where all your small program icons are located - see above picture for how it looks on Mac): - - 1. Find your `naisdevice` icon (pictured above - though it should not be red at first attempted connection). - - Can't find the icon? Make sure it is installed (See [macOS](#macos-installation), [Windows](#windows-installation) or [Ubuntu](#ubuntu-installation)) - 1. Left-click it and select `Connect`. - 1. Left-click the `naisdevice` icon again and click `Connect`. - You might need to allow ~20 seconds to pass before clicking `Connect` turns your `naisdevice` icon green. diff --git a/docs/how-to-guides/persistence/.pages b/docs/how-to-guides/persistence/.pages deleted file mode 100644 index b9e19f01..00000000 --- a/docs/how-to-guides/persistence/.pages +++ /dev/null @@ -1,6 +0,0 @@ -nav: - - buckets - - kafka - - opensearch - - redis - - postgres diff --git a/docs/how-to-guides/persistence/bigquery/.pages b/docs/how-to-guides/persistence/bigquery/.pages deleted file mode 100644 index 94581998..00000000 --- a/docs/how-to-guides/persistence/bigquery/.pages +++ /dev/null @@ -1 +0,0 @@ -title: BigQuery diff --git a/docs/how-to-guides/persistence/redis/.page b/docs/how-to-guides/persistence/redis/.page deleted file mode 100644 index 782bfe0f..00000000 --- a/docs/how-to-guides/persistence/redis/.page +++ /dev/null @@ -1 +0,0 @@ -title: Redis diff --git a/docs/how-to-guides/secrets/.pages b/docs/how-to-guides/secrets/.pages deleted file mode 100644 index b86614c2..00000000 --- a/docs/how-to-guides/secrets/.pages +++ /dev/null @@ -1,4 +0,0 @@ -nav: - - console.md - - workload.md - - ... diff --git a/docs/how-to-guides/workload-crud-operations.md b/docs/how-to-guides/workload-crud-operations.md deleted file mode 100644 index fd5f497c..00000000 --- a/docs/how-to-guides/workload-crud-operations.md +++ /dev/null @@ -1,77 +0,0 @@ -# Workload CRUD-operations - -This guide shows you how to perform CRUD-operations on your workload. - -## Prerequisites -- [Command-line access to the cluster](./command-line-access/setup.md) -- [Member of a NAIS team](../explanation/team.md) -- [Workload spec](../explanation/workloads/README.md) - -=== "Application" - - ## Create/apply the application spec - - ```shell - kubectl apply -f nais.yaml --namespace= --context= - ``` - - Verify that the application was successfully created by running `describe` on the Application: - - ```shell - kubectl describe app - ``` - - The events will tell you if the application was successfully created or not. - - - ## Read/list your applications - - ```shell - kubectl get application --namespace= --context= - ``` - - ## Update/edit your application - - ```shell - kubectl edit application --namespace= --context= - ``` - - ## Delete your application - - ```shell - kubectl delete application --namespace= --context= - ``` - -=== "Naisjob" - - ## Create/apply the naisjob spec - - ```shell - kubectl apply -f nais.yaml --namespace= --context= - ``` - - Verify that the naisjob was successfully created by running `describe` on the Naisjob: - - ```shell - kubectl describe naisjob - ``` - - The events will tell you if the naisjob was successfully created or not. - - ## Read/list your naisjobs - - ```shell - kubectl get naisjob --namespace= --context= - ``` - - ## Update/edit your naisjob - - ```shell - kubectl edit naisjob --namespace= --context= - ``` - - ## Delete your naisjob - - ```shell - kubectl delete naisjob --namespace= --context= - ``` diff --git a/docs/observability/.pages b/docs/observability/.pages new file mode 100644 index 00000000..f092fbf6 --- /dev/null +++ b/docs/observability/.pages @@ -0,0 +1,5 @@ +nav: +- README.md +- 🎯 How-To: how-to +- πŸ“š Reference: reference +- ... diff --git a/docs/explanation/observability/README.md b/docs/observability/README.md similarity index 93% rename from docs/explanation/observability/README.md rename to docs/observability/README.md index a69b0f1e..aa2d4fb4 100644 --- a/docs/explanation/observability/README.md +++ b/docs/observability/README.md @@ -4,8 +4,9 @@ description: >- This page describes the different options and how to use them. search: boost: 1 -tags: [explanation] +tags: [explanation, observability] --- + # Observability Building and deploying applications is only half the battle. The other half is to be able to observe what's going on in your application. This is where observability comes in. @@ -41,7 +42,7 @@ graph NAIS provides a new way to get started with observability. By enabling auto-instrumentation, you can get started with observability without having to write any code. This is the easiest way to get started with observability, as it requires little to no effort on the part of the team developing the application. -[:dart: Get started with auto-instrumentation](../../how-to-guides/observability/auto-instrumentation.md) +[:dart: Get started with auto-instrumentation](../observability/how-to/auto-instrumentation.md) ## Metrics @@ -51,7 +52,7 @@ We use the [OpenMetrics][openmetrics] format for metrics. This is a text-based f [openmetrics]: https://openmetrics.io/ -[:bulb: Learn more about metrics](./metrics.md) +[:bulb: Learn more about metrics](metrics/README.md) ### Prometheus @@ -67,7 +68,7 @@ graph LR Prometheus --GET /metrics--> Application ``` -[:simple-prometheus: Access Prometheus here](./metrics.md#prometheus-environments) +[:simple-prometheus: Access Prometheus here](metrics/README.md#prometheus-environments) ### Grafana @@ -92,7 +93,7 @@ graph LR Router --> C[Elastic / Kibana] ``` -[:bulb: Learn more about logs](./logging.md) +[:bulb: Learn more about logs](logging/README.md) ## Traces @@ -109,7 +110,7 @@ graph LR Tempo --> Grafana ``` -[:bulb: Learn more about tracing](./tracing.md) +[:bulb: Learn more about tracing](tracing/README.md) ## Alerts @@ -126,7 +127,7 @@ graph LR Alertmanager --> Slack ``` -[:bulb: Learn more about alerts](./alerting.md) +[:bulb: Learn more about alerts](alerting/README.md) ## Learning more diff --git a/docs/observability/alerting/.pages b/docs/observability/alerting/.pages new file mode 100644 index 00000000..f092fbf6 --- /dev/null +++ b/docs/observability/alerting/.pages @@ -0,0 +1,5 @@ +nav: +- README.md +- 🎯 How-To: how-to +- πŸ“š Reference: reference +- ... diff --git a/docs/explanation/observability/alerting.md b/docs/observability/alerting/README.md similarity index 98% rename from docs/explanation/observability/alerting.md rename to docs/observability/alerting/README.md index 47e57f09..c4be449c 100644 --- a/docs/explanation/observability/alerting.md +++ b/docs/observability/alerting/README.md @@ -1,8 +1,9 @@ --- description: >- Alerting is a crucial part of observability, and it's the first step in knowing when something is wrong with your application. -tags: [explanation] +tags: [explanation, alerting, observability, services] --- + # Alerting @@ -79,4 +80,4 @@ Consider the following attributes when setting up alerts: * https://cloud.google.com/blog/products/management-tools/practical-guide-to-setting-slos * https://cloud.google.com/blog/products/management-tools/good-relevance-and-outcomes-for-alerting-and-monitoring -* https://sre.google/workbook/implementing-slos/ \ No newline at end of file +* https://sre.google/workbook/implementing-slos/ diff --git a/docs/how-to-guides/observability/alerts/grafana.md b/docs/observability/alerting/how-to/grafana.md similarity index 85% rename from docs/how-to-guides/observability/alerts/grafana.md rename to docs/observability/alerting/how-to/grafana.md index cbe40fca..9032f85a 100644 --- a/docs/how-to-guides/observability/alerts/grafana.md +++ b/docs/observability/alerting/how-to/grafana.md @@ -1,7 +1,8 @@ --- description: Learn how to create an alert for your application in Grafana. -tags: [guide, grafana] +tags: [how-to, observability, alerting, grafana] --- + # Create alert in Grafana @@ -10,21 +11,21 @@ This guide shows you how to create an alert for your application in Grafana. Whi [howto-prometheus-alert]: ./prometheus-basic.md -## 0. Prerequisites +## Prerequisites You will need to have an application that exposes metrics. If you don't have one, you can follow the [Instrument Your Application][howto-instrument-application] guide. -You will need some basic knowledge of [PromQL](../../../reference/observability/metrics/promql.md) to create alert conditions. +You will need some basic knowledge of [PromQL](../../metrics/reference/promql.md) to create alert conditions. -[howto-instrument-application]: ../metrics/expose.md +[howto-instrument-application]: ../../metrics/how-to/expose.md -## 1. Create a new Alert rule +## Create a new Alert rule 1. Open [Grafana](<>) and navigate to "Alerting" > "[Alert rules](<>)" in the left-hand menu. 2. Click on "+ New alert rule" button. 3. Give your alert a descriptive name, you will choose a folder for it later. -## 2. Define query and alert condition +## Define query and alert condition Define queries and/or expressions and then choose one of them as the alert rule condition. This is the threshold that an alert rule must meet or exceed in order to fire. @@ -32,7 +33,7 @@ Define queries and/or expressions and then choose one of them as the alert rule 2. Write a PromQL query that returns the metric you want to alert on. For example, `http_requests_total{}`. 3. In the "Expression" field, write the condition that should trigger the alert. Choose the operator and the threshold value. For example, `IS ABOVE 100`. -## 3. Set evaluation behavior +## Set evaluation behavior Define how the alert rule is evaluated. @@ -40,7 +41,7 @@ Define how the alert rule is evaluated. 2. Leave "Evaluation group" empty unless you want to group this alert with others. 3. Set "Pending period" to the amount of time the alert condition must be met before the alert is triggered. -## 4. Add annotations +## Add annotations Add annotations to provide more context in your alert notifications. @@ -52,11 +53,11 @@ Add annotations to provide more context in your alert notifications. * `action` - Describes the action that should be taken when the alert is triggered. * `consequence` - Describes the observed consequence from the user's perspective. -## 5. Configure notifications +## Configure notifications Add custom labels to change the way your notifications are routed. * `app` - The application name. * `env` - The environment name. * `team` - The team name. -* `severity` - The severity of the alert. \ No newline at end of file +* `severity` - The severity of the alert. diff --git a/docs/how-to-guides/observability/alerts/prometheus-advanced.md b/docs/observability/alerting/how-to/prometheus-advanced.md similarity index 97% rename from docs/how-to-guides/observability/alerts/prometheus-advanced.md rename to docs/observability/alerting/how-to/prometheus-advanced.md index d859e42b..50080092 100644 --- a/docs/how-to-guides/observability/alerts/prometheus-advanced.md +++ b/docs/observability/alerting/how-to/prometheus-advanced.md @@ -1,16 +1,17 @@ --- description: Advanced guide to customized Promethues alerts -tags: [guide, prometheus] +tags: [how-to, alerting, observability, prometheus] --- + # Customize Prometheus alerts This guide will show you how to customize Promethues alerts for your team. This is useful if you want to experiment with formatting, use a different webhook, or have a different set of labels for your alerts. -## 0. Prerequisites +## Prerequisites Each team namespace will have a default `AlertmanagerConfig` which will pickup alerts labeled `namespace: `. If you want to change anything about alerting for your team, e.g. the formatting of alerts, webhook used, ..., you can create a simular `AlertmanagerConfig` which is configured for different labels -## 1. Create PrometheusRule +## Create PrometheusRule Remember that these matchers will match against every alert in the cluster, so be sure to use values that will be unique for your team. In your `PrometheusRule` also include the label `alert_type: custom` to be sure the default configuration doesn't pickup your alert. @@ -47,7 +48,7 @@ For more information about `slackConfigs` and other posibilites see the [Prometh alert_type: custom ``` -## 3. Create AlertmanagerConfig +## Create AlertmanagerConfig You can use an `AlertmanagerConfig` if you need to change the default slack layout, need another channel than the default channel, need another set of colors etc. diff --git a/docs/how-to-guides/observability/alerts/prometheus-basic.md b/docs/observability/alerting/how-to/prometheus-basic.md similarity index 84% rename from docs/how-to-guides/observability/alerts/prometheus-basic.md rename to docs/observability/alerting/how-to/prometheus-basic.md index 62191c3d..c751201c 100644 --- a/docs/how-to-guides/observability/alerts/prometheus-basic.md +++ b/docs/observability/alerting/how-to/prometheus-basic.md @@ -1,20 +1,21 @@ --- description: Create alerts for your application using Prometheus. -tags: [guide, prometheus] +tags: [how-to, observability, alerting, prometheus] --- + # Create alert with Prometheus This guide shows you how to create alerts for your application. -## 0. Prerequisites +## Prerequisites -- Your application serves [metrics](../metrics/expose.md) +- Your application serves [metrics](../../metrics/how-to/expose.md) You can define alerts by using Kubernetes resources (`PrometheusRule`), as well as directly in Grafana (GUI based). You will have a separate alertmanager for each environment available at `https://alertmanager..<>.cloud.nais.io/` -## 1. Create PrometheusRule +## Create PrometheusRule We use native [Prometheus alert rules](https://prometheus.io/docs/prometheus/latest/configuration/alerting_rules/), and let [Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/) handle the notifications. @@ -49,18 +50,19 @@ You can define alerts by creating a `PrometheusRule` resource in your teams name severity: critical ``` -## 2. Activate the alert +## Activate the alert === "Automatically" - Add the file to your application repository, alongside `nais.yaml` to deploy with [NAIS github action](../../github-action.md). -=== "Manually" + Add the file to your application repository, alongside `nais.yaml` to deploy with [NAIS github action](../../../build/how-to/build-and-deploy.md). + Some [link]( +=== "Manually" ```bash kubectl apply -f ./nais/alert.yaml ``` -## 3. Verify your alert +## Verify your alert You can see the alerts in the Alertmanager at `https://alertmanager..<>.cloud.nais.io/` and the defined rules in Prometheus at `https://prometheus..<>.cloud.nais.io/rules` -## 4. Disable resolved (Optional) +## Disable resolved (Optional) A message will be automatically sent when the alert is resolved. In some cases this message may be unnecessary and can be disabled by adding the label `send_resolved: "false"`: @@ -71,4 +73,4 @@ labels: send_resolved: "false" ``` -Learn how to write good alerts [here](../../../explanation/observability/alerting.md) +Learn how to write good alerts [here](../README.md) diff --git a/docs/reference/observability/alerts/prometheusrule.md b/docs/observability/alerting/reference/prometheusrule.md similarity index 91% rename from docs/reference/observability/alerts/prometheusrule.md rename to docs/observability/alerting/reference/prometheusrule.md index 648732fe..efb64b90 100644 --- a/docs/reference/observability/alerts/prometheusrule.md +++ b/docs/observability/alerting/reference/prometheusrule.md @@ -1,16 +1,17 @@ --- description: PrometheusRule resource specification for defining alerts in Prometheus. -tags: [reference, prometheus] +tags: [reference, observability, alerting, prometheus] --- + # Prometheus Alerting Rule Reference [Prometheus alerts][prometheus-alerting-rule] are defined in a `PrometheusRule` resource. This resource is part of the [Prometheus Operator][prometheus-operator] and is used to define alerts that should be sent to the Alertmanager. [Alertmanager][alertmanager] is a component of the Prometheus project that handles alerts sent by client applications such as the Prometheus server. It takes care of deduplicating, grouping, and routing them to the correct Slack channel. -Prometheus alerts are defined using the [PromQL](../metrics/promql.md) query language. The query language is used to specify when an alert should fire, and the `PrometheusRule` resource is used to specify the alert and its properties. +Prometheus alerts are defined using the [PromQL](../../metrics/reference/promql.md) query language. The query language is used to specify when an alert should fire, and the `PrometheusRule` resource is used to specify the alert and its properties. -Prometheus alerts are sent to the team's Slack channel configured in [nais teams](../../../explanation/team.md) when the alert fires. +Prometheus alerts are sent to the team's Slack channel configured in [Console](../../../operate/console.md) when the alert fires. ```mermaid graph LR diff --git a/docs/explanation/observability/frontend.md b/docs/observability/frontend/README.md similarity index 97% rename from docs/explanation/observability/frontend.md rename to docs/observability/frontend/README.md index 60964cb3..92de3e3a 100644 --- a/docs/explanation/observability/frontend.md +++ b/docs/observability/frontend/README.md @@ -2,8 +2,9 @@ description: >- NAIS offers observability tooling for frontend applications. This page describes how to use these offerings. -tags: [explanation] +tags: [explanation, observability, services] --- + # Frontend apps !!! info "Status: Alpha" @@ -129,7 +130,7 @@ context.with(trace.setSpan(context.active(), span), () => { When you deploy your frontend as a NAIS application, the telemetry collector URL can be automatically configured. -To use this feature, you must specify [frontend.mountPath.generatedConfig](../../reference/application-spec.md#frontendgeneratedconfigmountpath) in your `nais.yaml`. +To use this feature, you must specify [frontend.mountPath.generatedConfig](../../workloads/application/reference/application-spec.md#frontendgeneratedconfigmountpath) in your `nais.yaml`. A Javascript file will be created at the specified path in your pod file system, and contains the appropriate configuration. Additionally, the environment variable `NAIS_FRONTEND_TELEMETRY_COLLECTOR_URL` will be set in your pod. diff --git a/docs/how-to-guides/observability/auto-instrumentation.md b/docs/observability/how-to/auto-instrumentation.md similarity index 89% rename from docs/how-to-guides/observability/auto-instrumentation.md rename to docs/observability/how-to/auto-instrumentation.md index c4a69640..0b9edb0b 100644 --- a/docs/how-to-guides/observability/auto-instrumentation.md +++ b/docs/observability/how-to/auto-instrumentation.md @@ -1,10 +1,11 @@ --- description: Get started with auto-instrumentation for your applications with OpenTelemetry data for Tracing, Metrics and Logs using the OpenTelemetry Agent. -tags: [guide, tracing] +tags: [how-to, tracing, observability] --- + # Get started with auto-instrumentation -This guide will explain how to get started with auto-instrumentation your applications with OpenTelemetry data for [Tracing](../../explanation/observability/tracing.md), [Metrics](../../explanation/observability/metrics.md) and [Logs](../../explanation/observability/logging.md) using the OpenTelemetry Agent. +This guide will explain how to get started with auto-instrumentation your applications with OpenTelemetry data for [Tracing](../tracing/README.md), [Metrics](../metrics/README.md) and [Logs](../logging/README.md) using the OpenTelemetry Agent. The main benefit of auto-instrumentation is that is requires little to no effort on the part of the team developing the application while providing insight into popular libraries, frameworks and external services such as PostgreSQL, Redis, Kafka and HTTP clients. @@ -64,4 +65,4 @@ spec: ## Resources -[:books: OpenTelemetry Auto-Instrumentation Configuration Reference](../../reference/observability/auto-config.md) +[:books: OpenTelemetry Auto-Instrumentation Configuration Reference](../reference/auto-config.md) diff --git a/docs/observability/logging/.pages b/docs/observability/logging/.pages new file mode 100644 index 00000000..f092fbf6 --- /dev/null +++ b/docs/observability/logging/.pages @@ -0,0 +1,5 @@ +nav: +- README.md +- 🎯 How-To: how-to +- πŸ“š Reference: reference +- ... diff --git a/docs/explanation/observability/logging.md b/docs/observability/logging/README.md similarity index 94% rename from docs/explanation/observability/logging.md rename to docs/observability/logging/README.md index df9e09c5..4da0b137 100644 --- a/docs/explanation/observability/logging.md +++ b/docs/observability/logging/README.md @@ -1,8 +1,9 @@ --- description: >- Logs are a way to understand what is happening in your application. They are usually text-based and are often used for debugging. Since the format of logs is usually not standardized, it can be difficult to query and aggregate logs and thus we recommend using metrics for dashboards and alerting. -tags: [explanation] +tags: [explanation, logging, observability, services] --- + # Logging ## Purpose of logs @@ -35,7 +36,7 @@ Grafana Loki is a log aggregation system inspired by Prometheus and integrated w Loki is designed to be used in conjunction with metrics and tracing to provide a complete picture of an application's performance. Without the other two, it can be perceived as more cumbersome to use than a traditional logging system. -[:dart: Get started with Grafana Loki](../../how-to-guides/observability/logs/loki.md) +[:dart: Get started with Grafana Loki](how-to/loki.md) {% if tenant() == "nav" %} @@ -45,5 +46,5 @@ Loki is designed to be used in conjunction with metrics and tracing to provide a Kibana is a tool for visualizing and analyzing logs. It is part of the Elastic Stack and is widely used for log analysis and visualization in NAV. Kibana Elastic is supported by atom. -[:dart: Get started with Kibana](../../how-to-guides/observability/logs/kibana.md) +[:dart: Get started with Kibana](how-to/kibana.md) {% endif %} diff --git a/docs/how-to-guides/observability/logs/disable.md b/docs/observability/logging/how-to/disable.md similarity index 95% rename from docs/how-to-guides/observability/logs/disable.md rename to docs/observability/logging/how-to/disable.md index 1362af06..6aa64d5f 100644 --- a/docs/how-to-guides/observability/logs/disable.md +++ b/docs/observability/logging/how-to/disable.md @@ -1,7 +1,8 @@ --- description: Disable log storage for a specific application -tags: [guide] +tags: [how-to, logging, observability] --- + # Disable persistent application logs This guide will help you disable persistent log storage for an application. This is useful if you have an application whose logs are not useful or are causing too much noise in the logs. diff --git a/docs/how-to-guides/observability/logs/kubectl.md b/docs/observability/logging/how-to/kubectl.md similarity index 60% rename from docs/how-to-guides/observability/logs/kubectl.md rename to docs/observability/logging/how-to/kubectl.md index 7fa08a8f..72df97fe 100644 --- a/docs/how-to-guides/observability/logs/kubectl.md +++ b/docs/observability/logging/how-to/kubectl.md @@ -1,17 +1,18 @@ --- description: View logs from the command line using kubectl. -tags: [guide, kubectl] +tags: [how-to, logging, observability, command-line] --- + # View logs from the command line This guide will show you how to view logs from the command line using `kubectl`. -## 0. Prerequisites +## Prerequisites -- You have installed the [kubectl](../../command-line-access/setup.md) command-line tool. -- You have access to the [team](../../team.md) where the application is running. +- You have installed the [kubectl](../../../operate/how-to/command-line-access.md) command-line tool. +- You have access to the [team](../../../explanations/team.md) where the application is running. -## 1. Find the pod name +## Find the pod name You can view logs for a specific pod. First, you need to find the name of the pod you want to view logs for. @@ -21,7 +22,7 @@ List all pods in the namespace: kubectl get pods -n ``` -## 2. View logs +## View logs View logs for a specific pod: diff --git a/docs/how-to-guides/observability/logs/loki.md b/docs/observability/logging/how-to/loki.md similarity index 81% rename from docs/how-to-guides/observability/logs/loki.md rename to docs/observability/logging/how-to/loki.md index ec52baa1..dbbc056f 100644 --- a/docs/how-to-guides/observability/logs/loki.md +++ b/docs/observability/logging/how-to/loki.md @@ -1,7 +1,8 @@ --- description: Get started with Grafana Loki, a log aggregation system that is integrated with Grafana and inspired by Prometheus. -tags: [guide, loki] +tags: [how-to, logging, observability, loki] --- + # Get started with Grafana Loki This guide will help you get started with Grafana Loki, a log aggregation system that is integrated with Grafana and inspired by Prometheus. @@ -27,7 +28,7 @@ Grafana Loki can be enabled by setting the list of logging destinations in your Grafana Loki is integrated directly with Grafana, and you can access your logs either by adding a Logs Panel to your dashboard or by clicking on the "[Explore](<>)" link on the left-hand side of the Grafana UI and selecting one of the Loki data sources (one for each environment). -Grafana Loki has a query language called [LogQL](../../../reference/observability/logs/logql.md) that you can use to search for logs. LogQL is a simplified version of PromQL, and you can use LogQL to search for logs by message, by field, or by a combination of both. +Grafana Loki has a query language called [LogQL](../reference/logql.md) that you can use to search for logs. LogQL is a simplified version of PromQL, and you can use LogQL to search for logs by message, by field, or by a combination of both. To get you started we suggest using the query builder mode when writing your first LogQL queries. The query builder mode is a graphical interface that helps you build LogQL queries by selecting labels and fields from your logs. @@ -35,4 +36,4 @@ To get you started we suggest using the query builder mode when writing your fir ## Further reading -- [LogQL reference](../../../reference/observability/logs/logql.md) \ No newline at end of file +- [LogQL reference](../reference/logql.md) diff --git a/docs/reference/observability/logs/logql.md b/docs/observability/logging/reference/logql.md similarity index 96% rename from docs/reference/observability/logs/logql.md rename to docs/observability/logging/reference/logql.md index 918977e1..f50c5e51 100644 --- a/docs/reference/observability/logs/logql.md +++ b/docs/observability/logging/reference/logql.md @@ -1,10 +1,10 @@ --- description: LogQL reference documentation for querying logs in Grafana Loki. -tags: [reference, loki] +tags: [reference, loki, logging] --- # LogQL Reference -LogQL is the query language used in Grafana Loki to query logs. It is a powerful query language that allows you to filter, aggregate, and search for logs and should be familiar to anyone who has used SQL or [PromQL](../metrics/promql.md). +LogQL is the query language used in Grafana Loki to query logs. It is a powerful query language that allows you to filter, aggregate, and search for logs and should be familiar to anyone who has used SQL or [PromQL](../../metrics/reference/promql.md). Where LogQL differs from PromQL is it's trailing pipeline syntax, or log pipeline. A log pipeline is a set of stage expressions that are chained together and applied to the selected log streams. Each expression can filter out, parse, or mutate log lines and their respective labels. diff --git a/docs/observability/metrics/.pages b/docs/observability/metrics/.pages new file mode 100644 index 00000000..f092fbf6 --- /dev/null +++ b/docs/observability/metrics/.pages @@ -0,0 +1,5 @@ +nav: +- README.md +- 🎯 How-To: how-to +- πŸ“š Reference: reference +- ... diff --git a/docs/explanation/observability/metrics.md b/docs/observability/metrics/README.md similarity index 94% rename from docs/explanation/observability/metrics.md rename to docs/observability/metrics/README.md index fbeff6a6..c12956af 100644 --- a/docs/explanation/observability/metrics.md +++ b/docs/observability/metrics/README.md @@ -1,10 +1,11 @@ --- description: Metrics are a way to measure the state of your application and can be used to create alerts in Prometheus and dashboards in Grafana. -tags: [explanation] +tags: [explanation, metrics, observability, services] --- + # Metrics -See [how to](../../how-to-guides/observability/metrics/expose.md) set up metrics. +See [how to](how-to/expose.md) set up metrics. Metrics are a way to measure the state of your application from within and something that is built into a microservice architecture from the very beginning. We suggest you start with the basics, that is defining what is fascinating to your team to track in terms of service health and level of service quality. @@ -24,7 +25,7 @@ graph LR ``` [openmetrics]: https://openmetrics.io/ -[nais-manifest-prometheus]: ../../reference/application-spec.md#prometheus +[nais-manifest-prometheus]: ../../workloads/application/reference/application-spec.md#prometheus All applications that have Prometheus scraping enabled will show up in the [default Grafana dashboard](https://grafana.<>.cloud.nais.io/d/000000283/nais-app-dashbord), or create their own. @@ -70,7 +71,7 @@ You should, as a developer, that build metrics into your application have solid NAIS clusters comes with a set of metrics that are available for all applications. Many of these relates to Kubernetes and includes metrics like CPU and memory usage, number of pods, etc. You can find a comprehensive list in the [kube-state-metrics documentation](https://github.com/kubernetes/kube-state-metrics/blob/master/docs/README.md). -Our ingress controller also exposes metrics about the number of requests, response times, etc. You can find a comprehensive list in our [ingress documentation](../../reference//ingress.md#ingress-metrics). +Our ingress controller also exposes metrics about the number of requests, response times, etc. You can find a comprehensive list in our [ingress documentation](../../workloads/reference/ingress.md#ingress-metrics). ## Debugging metrics @@ -90,4 +91,4 @@ List of Prometheus environments: {% else %} * <> * <> -{% endif %} \ No newline at end of file +{% endif %} diff --git a/docs/how-to-guides/observability/metrics/dashboard.md b/docs/observability/metrics/how-to/dashboard.md similarity index 98% rename from docs/how-to-guides/observability/metrics/dashboard.md rename to docs/observability/metrics/how-to/dashboard.md index 4a72449c..d0a7bac8 100644 --- a/docs/how-to-guides/observability/metrics/dashboard.md +++ b/docs/observability/metrics/how-to/dashboard.md @@ -1,7 +1,8 @@ --- description: Create a dashboard in Grafana for your application -tags: [guide, grafana] +tags: [how-to, grafana, observability, metrics] --- + # Create a dashboard in Grafana This guide shows you how to create a dashboard in Grafana for your application. Grafana is a popular open-source visualization and analytics platform that allows you to query, visualize, alert on, and understand your metrics no matter where they are stored. diff --git a/docs/how-to-guides/observability/metrics/expose.md b/docs/observability/metrics/how-to/expose.md similarity index 79% rename from docs/how-to-guides/observability/metrics/expose.md rename to docs/observability/metrics/how-to/expose.md index 4e4a0dbd..b2ef9893 100644 --- a/docs/how-to-guides/observability/metrics/expose.md +++ b/docs/observability/metrics/how-to/expose.md @@ -1,12 +1,12 @@ --- description: Expose metrics from your application -tags: [guide, prometheus] +tags: [how-to, metrics, prometheus, observability] --- # Expose metrics from your application This guide will show you how to expose metrics from your application, and how to configure Prometheus to scrape them. -See further [explanations on metrics](../../../explanation/observability/metrics.md) for more details +See further [explanations on metrics](../README.md) for more details ## 1. Add metric to your application @@ -14,7 +14,7 @@ Most languages have a Prometheus client library available. See [Prometheus clien Once instrumented, your application must serve these metrics using HTTP on a given `path` (e.g. `/metrics`). -## 2. Enable metrics in [manifest](../../../reference/application-spec.md) +## 2. Enable metrics in [manifest](../../../workloads/application/reference/application-spec.md) ```yaml spec: diff --git a/docs/how-to-guides/observability/metrics/push.md b/docs/observability/metrics/how-to/push.md similarity index 93% rename from docs/how-to-guides/observability/metrics/push.md rename to docs/observability/metrics/how-to/push.md index 1d6bb387..a0bb4df5 100644 --- a/docs/how-to-guides/observability/metrics/push.md +++ b/docs/observability/metrics/how-to/push.md @@ -1,6 +1,6 @@ --- description: Push metrics to Prometheus -tags: [guide, prometheus] +tags: [how-to, observability, metrics, prometheus] --- # Push metrics to Prometheus @@ -9,7 +9,7 @@ This is typically used in NAIS jobs, which by it's nature often is short-lived a Prometheus has further explanations and examples [here](https://prometheus.io/docs/instrumenting/pushing/) -## 1. Add pushgateway and accessPolicy to your manifest +## Add pushgateway and accessPolicy to your manifest ???+ note ".nais/naisjob.yaml" @@ -34,7 +34,7 @@ Prometheus has further explanations and examples [here](https://prometheus.io/do namespace: nais-system ``` -## 2. Send metrics to your application +## Send metrics to your application ```java package io.prometheus.client.it.pushgateway; diff --git a/docs/reference/observability/metrics/globals.md b/docs/observability/metrics/reference/globals.md similarity index 100% rename from docs/reference/observability/metrics/globals.md rename to docs/observability/metrics/reference/globals.md diff --git a/docs/reference/observability/metrics/grafana.md b/docs/observability/metrics/reference/grafana.md similarity index 87% rename from docs/reference/observability/metrics/grafana.md rename to docs/observability/metrics/reference/grafana.md index 4d40d2c8..ab09e54d 100644 --- a/docs/reference/observability/metrics/grafana.md +++ b/docs/observability/metrics/reference/grafana.md @@ -1,5 +1,5 @@ --- -tags: [reference, grafana] +tags: [reference, grafana, metrics] --- # Grafana Glossary @@ -10,7 +10,7 @@ This glossary contains terms and concepts related to Grafana. A dashboard is a collection of panels arranged in a grid layout. Each panel is a single visualization or a single query result. You can add multiple panels to a dashboard to create a complete view of your application. -* [Guide: Create a dashboard in Grafana](../../../how-to-guides/observability/metrics/dashboard.md) +* [Guide: Create a dashboard in Grafana](../how-to/dashboard.md) * [Grafana docs: Dashboards](https://grafana.com/docs/grafana/latest/dashboards/) ## Panel @@ -38,4 +38,4 @@ A visualization is a graphical representation of your data. Grafana supports a v Grafana has a built-in alerting system that allows you to set up alerts for your metrics. You can create alert rules that are evaluated at regular intervals, and when the alert rule conditions are met, Grafana will send notifications to the configured notification channels. -* [Guide: Alerting in Grafana](../../../how-to-guides/observability/alerts/grafana.md) \ No newline at end of file +* [Guide: Alerting in Grafana](../../alerting/how-to/grafana.md) diff --git a/docs/reference/metrics.md b/docs/observability/metrics/reference/metrics.md similarity index 80% rename from docs/reference/metrics.md rename to docs/observability/metrics/reference/metrics.md index 6368fd11..4bd8e57d 100644 --- a/docs/reference/metrics.md +++ b/docs/observability/metrics/reference/metrics.md @@ -1,9 +1,13 @@ +--- +tags: [reference, metrics, prometheus] +--- + # Metrics reference ## Retention When using Prometheus the retention is 30 days. -If you need data stored longer than what Prometheus support, we recommend using [BigQuery](../how-to-guides/persistence/bigquery/create.md). +If you need data stored longer than what Prometheus support, we recommend using [BigQuery](../../../persistence/bigquery/README.md). Then you have full control of the database and retention. ## Accessing prometheus diff --git a/docs/reference/observability/metrics/otel.md b/docs/observability/metrics/reference/otel.md similarity index 98% rename from docs/reference/observability/metrics/otel.md rename to docs/observability/metrics/reference/otel.md index 6730636a..3b73af00 100644 --- a/docs/reference/observability/metrics/otel.md +++ b/docs/observability/metrics/reference/otel.md @@ -1,3 +1,7 @@ +--- +tags: [reference, otel, observability, metrics] +--- + # OpenTelemetry Metrics This is a list of metrics exported by the OpenTelemetry SDKs and auto-instrumentation libraries. diff --git a/docs/reference/observability/metrics/promql.md b/docs/observability/metrics/reference/promql.md similarity index 89% rename from docs/reference/observability/metrics/promql.md rename to docs/observability/metrics/reference/promql.md index 5479bd5e..479ea8f7 100644 --- a/docs/reference/observability/metrics/promql.md +++ b/docs/observability/metrics/reference/promql.md @@ -1,13 +1,14 @@ --- description: PromQL reference documentation for querying metrics in Prometheus. -tags: [reference, prometheus] +tags: [reference, prometheus, metrics] --- + # PromQL Reference PromQL is a query language for Prometheus monitoring system. It allows you to select and aggregate time series data in real time. PromQL is used to [create dashboards in Grafana][howto-grafana-dashboard], and to [create alerts with Alertmanager][howto-alertmanager-alerts]. -[howto-grafana-dashboard]: ../../../how-to-guides/observability/metrics/dashboard.md -[howto-alertmanager-alerts]: ../../../how-to-guides/observability/alerts/prometheus-basic.md +[howto-grafana-dashboard]: ../how-to/dashboard.md +[howto-alertmanager-alerts]: ../../alerting/how-to/prometheus-basic.md ## Basic Syntax diff --git a/docs/reference/observability/auto-config.md b/docs/observability/reference/auto-config.md similarity index 94% rename from docs/reference/observability/auto-config.md rename to docs/observability/reference/auto-config.md index 549381e1..91654d4f 100644 --- a/docs/reference/observability/auto-config.md +++ b/docs/observability/reference/auto-config.md @@ -1,16 +1,20 @@ +--- +tags: [observability, reference] +--- + # OpenTelemetry Auto-Instrumentation Configuration -When you enable [auto-instrumentation](../../how-to-guides/observability/auto-instrumentation.md) in your application the following OpenTelemetry configuration will become available to your application as environment variables: +When you enable [auto-instrumentation](../how-to/auto-instrumentation.md) in your application the following OpenTelemetry configuration will become available to your application as environment variables: | Variable | Example Value | -| ------------------------------------ | --------------------------------------------------------------------------------------------- | +|--------------------------------------|-----------------------------------------------------------------------------------------------| | `OTEL_SERVICE_NAME` | `my-application` | | `OTEL_EXPORTER_OTLP_ENDPOINT` | `http://opentelemetry-collector.nais-system:4317` | | `OTEL_EXPORTER_OTLP_PROTOCOL` | `grpc` | | `OTEL_EXPORTER_OTLP_INSECURE` | `true` | | `OTEL_PROPAGATORS` | `tracecontext,baggage` | | `OTEL_TRACES_SAMPLER` | `parentbased_always_on` | -| `OTLE_LOGS_EXPORTER` | `none` | +| `OTEL_LOGS_EXPORTER` | `none` | | `OTEL_RESOURCE_ATTRIBUTES_POD_NAME` | `my-application-777787df6d-pw9mq` | | `OTEL_RESOURCE_ATTRIBUTES_NODE_NAME` | `gke-node-abc123` | | `OTEL_RESOURCE_ATTRIBUTES` | `service.name=my-application,service.namespace=my-team,k8s.container.name=my-application,...` | diff --git a/docs/reference/glossary.md b/docs/observability/reference/glossary.md similarity index 97% rename from docs/reference/glossary.md rename to docs/observability/reference/glossary.md index 07cffff1..97a96452 100644 --- a/docs/reference/glossary.md +++ b/docs/observability/reference/glossary.md @@ -1,4 +1,8 @@ -# A nais glossary +--- +tags: [observability, reference] +--- + +# Observability Glossary ## Observability diff --git a/docs/observability/tracing/.pages b/docs/observability/tracing/.pages new file mode 100644 index 00000000..f092fbf6 --- /dev/null +++ b/docs/observability/tracing/.pages @@ -0,0 +1,5 @@ +nav: +- README.md +- 🎯 How-To: how-to +- πŸ“š Reference: reference +- ... diff --git a/docs/explanation/observability/tracing.md b/docs/observability/tracing/README.md similarity index 95% rename from docs/explanation/observability/tracing.md rename to docs/observability/tracing/README.md index 4bef69fb..8f8f9aa1 100644 --- a/docs/explanation/observability/tracing.md +++ b/docs/observability/tracing/README.md @@ -1,7 +1,7 @@ --- description: >- Application Performance Monitoring or tracing using Grafana Tempo on NAIS. -tags: [explanation, tracing] +tags: [explanation, observability, tracing, services] --- # Distributed Tracing @@ -48,7 +48,7 @@ The preferred way to get started with tracing is to enable auto-instrumentation This is the easiest way to get started with tracing, as it requires little to no effort on the part of the team developing the application and provides instrumentation for popular libraries, frameworks and external services such as PostgreSQL, Redis, Kafka and HTTP clients. -[:dart: Get started with auto-instrumentation](../../how-to-guides/observability/auto-instrumentation.md) +[:dart: Get started with auto-instrumentation](../how-to/auto-instrumentation.md) ### The hard way: Manual instrumentation @@ -56,7 +56,7 @@ If you want more control over how your application is instrumented, you can manu To get the correct configuration for you can still use the auto-instrumentation configuration, but set the `runtime` to `sdk` as this will only set up the OpenTelemetry configuration, without injecting the OpenTelemetry Agent. -[:dart: Get started with manual-instrumentation](../../how-to-guides/observability/auto-instrumentation.md#enable-auto-instrumentation-for-other-applications) +[:dart: Get started with manual-instrumentation](../how-to/auto-instrumentation.md#enable-auto-instrumentation-for-other-applications) ### OpenTelemetry SDKs @@ -114,7 +114,7 @@ The easiest way to get started with Tempo is to use the *Explore view* in Grafan [:simple-grafana: Open Grafana Explore][grafana-explore] -[:dart: Get started with Grafana Tempo](../../how-to-guides/observability/tracing/tempo.md) +[:dart: Get started with Grafana Tempo](how-to/tempo.md) ![Grafana Tempo](../../assets/grafana-tempo.png) diff --git a/docs/how-to-guides/observability/tracing/context-propagation.md b/docs/observability/tracing/how-to/context-propagation.md similarity index 88% rename from docs/how-to-guides/observability/tracing/context-propagation.md rename to docs/observability/tracing/how-to/context-propagation.md index aae017b6..a4737f8c 100644 --- a/docs/how-to-guides/observability/tracing/context-propagation.md +++ b/docs/observability/tracing/how-to/context-propagation.md @@ -1,12 +1,13 @@ --- description: Learn how to propagate trace context across process boundaries in a few common scenarios. -tags: [guide, tracing] +tags: [how-to, tracing, observability] --- + # Trace context propagation Each Span carries a Context that includes metadata about the trace (like a unique trace identifier and span identifier) and any other data you choose to include. This context is propagated across process boundaries, allowing all the work that's part of a single trace to be linked together, even if it spans multiple services. -This guide explains how to propagate trace context across process boundaries in a few common scenarios. If you are using [auto-instrumentation](../auto-instrumentation.md), trace context propagation is already handled for you. +This guide explains how to propagate trace context across process boundaries in a few common scenarios. If you are using [auto-instrumentation](../../how-to/auto-instrumentation.md), trace context propagation is already handled for you. [:octicons-link-external-24: OpenTelemetry Context Propagation on opentelemetry.io](https://opentelemetry.io/docs/concepts/context-propagation/) @@ -15,4 +16,4 @@ This guide explains how to propagate trace context across process boundaries in When a service makes an HTTP request to another service, it should include the trace context in the request headers. The receiving service can then use this context to create a new Span that's part of the same trace. OpenTelemetry provides a standard for how trace context should be propagated in HTTP requests, called the [W3C Trace Context](https://www.w3.org/TR/trace-context/) standard. * [OpenTelemetry Setup in Spring Boot Application](https://opentelemetry.io/docs/languages/java/automatic/spring-boot) -* [OpenTelemetry Setup in Ktor Application](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/ktor/ktor-2.0/library) \ No newline at end of file +* [OpenTelemetry Setup in Ktor Application](https://github.com/open-telemetry/opentelemetry-java-instrumentation/tree/main/instrumentation/ktor/ktor-2.0/library) diff --git a/docs/how-to-guides/observability/tracing/correlate-traces-logs.md b/docs/observability/tracing/how-to/correlate-traces-logs.md similarity index 91% rename from docs/how-to-guides/observability/tracing/correlate-traces-logs.md rename to docs/observability/tracing/how-to/correlate-traces-logs.md index 089b4bcc..0cd6766b 100644 --- a/docs/how-to-guides/observability/tracing/correlate-traces-logs.md +++ b/docs/observability/tracing/how-to/correlate-traces-logs.md @@ -1,24 +1,24 @@ --- description: Learn how to correlate traces with logs in Grafana Tempo. -tags: [guide, tracing] +tags: [how-to, tracing, observability] --- # Correlate traces and logs This guide will explain how to correlate traces with logs in Grafana Tempo. This is only necessary if you are not using auto-instrumentation with OpenTelemetry Agent. If you are using auto-instrumentation, logs are automatically correlated with traces. -## Step 1: Configure Tracing +## Configure Tracing First you need to configure OpenTelemetry tracing in your application. The easiest way to get started with tracing is to enable auto-instrumentation for your application. This will automatically collect traces and send them to the correct place using the OpenTelemetry Agent or you can use the OpenTelemetry SDK to manually instrument your application. -[:dart: Get started with auto-instrumentation](../auto-instrumentation.md) +[:dart: Get started with auto-instrumentation](../../how-to/auto-instrumentation.md) -## Step 2: Enable logging to Grafana Loki +## Enable logging to Grafana Loki In order to use the Grafana Tempo log correlation feature, you need to send your logs to Grafana Loki. -[:dart: Enable logging to Grafana Loki](../logs/loki.md#enable-logging-to-grafana-loki) +[:dart: Enable logging to Grafana Loki](../../logging/how-to/loki.md#enable-logging-to-grafana-loki) -## Step 3: Include trace information in your logs +## Include trace information in your logs The final step is to include trace information in your logs. This will allow Grafana Tempo to look up logs that are associated with a trace. @@ -79,8 +79,9 @@ The final step is to include trace information in your logs. This will allow Gra ``` -## 4. Profit +## Profit Now that you have tracing and logging set up, you can use Grafana Tempo to correlate traces and logs. When you view a trace in Grafana Tempo, you can see the logs that are associated with that trace. This makes it easy to understand what happened in your application and troubleshoot issues. ![Correlate traces and logs](../../../assets/grafana-tempo-logs.png) + diff --git a/docs/how-to-guides/observability/tracing/tempo.md b/docs/observability/tracing/how-to/tempo.md similarity index 93% rename from docs/how-to-guides/observability/tracing/tempo.md rename to docs/observability/tracing/how-to/tempo.md index cf7093be..9396778f 100644 --- a/docs/how-to-guides/observability/tracing/tempo.md +++ b/docs/observability/tracing/how-to/tempo.md @@ -1,10 +1,14 @@ +--- +tags: [how-to, tracing, tempo, observability] +--- + # Get started with Grafana Tempo Grafana Tempo is an open-source, easy-to-use, high-scale, and cost-effective distributed tracing backend that stores and queries traces in a way that is easy to understand and use. It is fully integrated with Grafana, allowing you to visualize and query traces in the same interface as your metrics, and logs. Since NAIS does not collect application trace data automatically, you need to enable tracing in your application. The preferred way to get started with tracing is to enable auto-instrumentation for your application. This will automatically collect traces and send them to the correct place using the OpenTelemetry Agent. -[:dart: Get started with auto-instrumentation](../auto-instrumentation.md) +[:dart: Get started with auto-instrumentation](../../how-to/auto-instrumentation.md) Once you have traces being collected, you can visualize and query them in Grafana using the Grafana Tempo data source. To get started with Tempo, you can use the Explore view in Grafana, which provides a user-friendly interface for querying and visualizing traces. @@ -34,7 +38,7 @@ TraceQL provides a powerful and flexible way to query trace data, and it is desi -[:books: Learn more about TraceQL query language](../../../reference/observability/tracing/traceql.md) +[:books: Learn more about TraceQL query language](../reference/traceql.md) ## Understanding trace data @@ -48,5 +52,5 @@ A red circle next to a span indicates that the span has an error. You can click Traces in nais follows the OpenTelemetry Semantic Conventions, which provides a standard for naming and structuring trace data. This makes it easier to understand and use trace data, as you can rely on a consistent structure across all traces. -[:books: Learn more about OpenTelemetry Trace Semantic Conventions](../../../reference/observability/tracing/trace-semconv.md) +[:books: Learn more about OpenTelemetry Trace Semantic Conventions](../reference/trace-semconv.md) diff --git a/docs/reference/observability/tracing/trace-semconv.md b/docs/observability/tracing/reference/trace-semconv.md similarity index 76% rename from docs/reference/observability/tracing/trace-semconv.md rename to docs/observability/tracing/reference/trace-semconv.md index f3648708..110b5a44 100644 --- a/docs/reference/observability/tracing/trace-semconv.md +++ b/docs/observability/tracing/reference/trace-semconv.md @@ -1,3 +1,7 @@ +--- +tags: [reference, otel, observability, tracing] +--- + # OpenTelemetry Trace Semantic Conventions OpenTelemetry Trace Semantic Conventions can be found at [opentelemetry.io](https://opentelemetry.io/docs/specs/semconv/general/trace/). diff --git a/docs/reference/observability/tracing/traceql.md b/docs/observability/tracing/reference/traceql.md similarity index 97% rename from docs/reference/observability/tracing/traceql.md rename to docs/observability/tracing/reference/traceql.md index 6e9de4ad..003cc9d5 100644 --- a/docs/reference/observability/tracing/traceql.md +++ b/docs/observability/tracing/reference/traceql.md @@ -1,10 +1,10 @@ --- description: TraceQL reference documentation for querying traces in Grafana Tempo. -tags: [reference, tempo] +tags: [reference, tempo, tracing] --- # TraceQL Reference -TraceQL is the query language used in Grafana Tempo to query traces. It is a powerful query language that allows you to filter, aggregate, and search for traces and should be familiar to anyone who has used SQL or [PromQL](../metrics/promql.md). +TraceQL is the query language used in Grafana Tempo to query traces. It is a powerful query language that allows you to filter, aggregate, and search for traces and should be familiar to anyone who has used SQL or [PromQL](../../metrics/reference/promql.md). Where TraceQL differs from PromQL is it's trailing pipeline syntax, or trace pipeline. A trace pipeline is a set of stage expressions that are chained together and applied to the selected trace data. Each expression can filter out, parse, or mutate trace spans and their respective labels. diff --git a/docs/operate/.pages b/docs/operate/.pages new file mode 100644 index 00000000..40247fcc --- /dev/null +++ b/docs/operate/.pages @@ -0,0 +1,7 @@ +nav: +- README.md +- 🎯 How-To: how-to +- Console: console.md +- CLI: cli +- naisdevice: naisdevice +- ... diff --git a/docs/operate/README.md b/docs/operate/README.md new file mode 100644 index 00000000..e59e52c2 --- /dev/null +++ b/docs/operate/README.md @@ -0,0 +1,18 @@ +--- +tags: [explanation, operate] +--- + +# Manage your workloads and services + +This section covers how to manage your workloads and services on the NAIS platform. +It describes the different options available, and how to use them. + +Most of the management tasks can be done through the [NAIS Console](console.md), which is a web-based interface. + +Some more advanced use-cases still requires you to interact with the platform using the Kubernetes CLI, `kubectl`. + +## What's next? + +:bulb: [Learn more about Console](console.md) + +:dart: [Setup command line access](how-to/command-line-access.md) diff --git a/docs/operate/cli/.pages b/docs/operate/cli/.pages new file mode 100644 index 00000000..68abb12b --- /dev/null +++ b/docs/operate/cli/.pages @@ -0,0 +1,5 @@ +title: nais-cli +nav: + - ... + - 🎯 How-To: how-to + - πŸ“š Reference: reference diff --git a/docs/operate/cli/README.md b/docs/operate/cli/README.md new file mode 100644 index 00000000..0c6f7bbd --- /dev/null +++ b/docs/operate/cli/README.md @@ -0,0 +1,30 @@ +# nais-cli + +nais-cli is a CLI application that provides some useful commands and utilities for interacting with the NAIS platform. + +## Prerequisites + +- [naisdevice](../naisdevice/README.md) + +## Installation + +- [Install nais-cli](how-to/install.md) + +## Usage + +See available subcommands under the Reference section in the navigation sidebar. + +!!! warning "Flag ordering" + + nais-cli requires all flags to appear **before** arguments. Otherwise, the flags will be interpreted as arguments. + + :white_check_mark: OK: + ```shell + nais start --topics events appname teamname + ``` + + :x: Not OK: + + ```shell + nais start appname teamname --topics events + ``` diff --git a/docs/how-to-guides/nais-cli/install.md b/docs/operate/cli/how-to/install.md similarity index 95% rename from docs/how-to-guides/nais-cli/install.md rename to docs/operate/cli/how-to/install.md index c4cc1380..b89d6cad 100644 --- a/docs/how-to-guides/nais-cli/install.md +++ b/docs/operate/cli/how-to/install.md @@ -1,4 +1,8 @@ -# Install +--- +tags: [command-line, how-to] +--- + +# Install nais-cli === "macOS" diff --git a/docs/how-to-guides/nais-cli/troubleshooting.md b/docs/operate/cli/how-to/troubleshooting.md similarity index 95% rename from docs/how-to-guides/nais-cli/troubleshooting.md rename to docs/operate/cli/how-to/troubleshooting.md index 7b690ae6..e056c3a9 100644 --- a/docs/how-to-guides/nais-cli/troubleshooting.md +++ b/docs/operate/cli/how-to/troubleshooting.md @@ -1,4 +1,8 @@ -# Troubleshooting +--- +tags: [command-line, how-to] +--- + +# Troubleshooting nais-cli ## `Could not create process with command` diff --git a/docs/reference/cli/device.md b/docs/operate/cli/reference/device.md similarity index 94% rename from docs/reference/cli/device.md rename to docs/operate/cli/reference/device.md index f3f55825..82705193 100644 --- a/docs/reference/cli/device.md +++ b/docs/operate/cli/reference/device.md @@ -1,6 +1,10 @@ +--- +tags: [command-line, reference] +--- + # device command -The device command can be used to connect to, disconnect from, and view the connection status of [naisdevice](../../explanation/naisdevice.md). +The device command can be used to connect to, disconnect from, and view the connection status of [naisdevice](../../naisdevice/README.md). Currently, the command requires the processes `naisdevice-agent` and `naisdevice-helper` to run, both of which can be run by starting naisdevice. ## connect diff --git a/docs/reference/cli/kubeconfig.md b/docs/operate/cli/reference/kubeconfig.md similarity index 96% rename from docs/reference/cli/kubeconfig.md rename to docs/operate/cli/reference/kubeconfig.md index 2b5b1992..95cdde70 100644 --- a/docs/reference/cli/kubeconfig.md +++ b/docs/operate/cli/reference/kubeconfig.md @@ -1,3 +1,7 @@ +--- +tags: [command-line, reference] +--- + # kubeconfig command Create a kubeconfig file for connecting to available clusters for you. diff --git a/docs/reference/cli/postgres.md b/docs/operate/cli/reference/postgres.md similarity index 99% rename from docs/reference/cli/postgres.md rename to docs/operate/cli/reference/postgres.md index fa144c1d..40894060 100644 --- a/docs/reference/cli/postgres.md +++ b/docs/operate/cli/reference/postgres.md @@ -1,3 +1,7 @@ +--- +tags: [command-line, reference] +--- + # postgres command The postgres command can be used to connect to a cloudsql postgres database with your personal user diff --git a/docs/reference/cli/validate.md b/docs/operate/cli/reference/validate.md similarity index 92% rename from docs/reference/cli/validate.md rename to docs/operate/cli/reference/validate.md index 4b7cf91e..22ccc85b 100644 --- a/docs/reference/cli/validate.md +++ b/docs/operate/cli/reference/validate.md @@ -1,3 +1,7 @@ +--- +tags: [command-line, reference] +--- + # validate command ```bash @@ -30,9 +34,9 @@ See the [templating section](#templating) for examples. The following resource kinds are supported: -- [Application](../application-example.md) -- [Naisjob](../naisjob-example.md) -- [Topic (Kafka)](../kafka-topic-example.md) +- [Application](../../../workloads/application/reference/application-example.md) +- [Naisjob](../../../workloads/job/reference/naisjob-example.md) +- [Topic (Kafka)](../../../persistence/kafka/reference/kafka-topic-example.md) ## Templating diff --git a/docs/operate/console.md b/docs/operate/console.md new file mode 100644 index 00000000..b58f352b --- /dev/null +++ b/docs/operate/console.md @@ -0,0 +1,13 @@ +--- +tags: [console, explanation, operate] +--- + +# Console + +NAIS Console is a web-based interface for managing your workloads and services on the NAIS platform. It aims to provide a user-friendly way to interact with the platform, without needing to use the command line. + +It tries to provide you with insight into what you've got running on the platform. Is everything running as expected? Are you utilizing the resources you allocate effectively? + +The Console is designed to be self-service, meaning that you can manage your workloads and services without needing to involve the NAIS team. This includes creating, updating, and deleting workloads, as well as managing secrets and other resources. + +Access Console at [console.<>.cloud.nais.io](https://console.<>.cloud.nais.io). diff --git a/docs/how-to-guides/command-line-access/setup.md b/docs/operate/how-to/command-line-access.md similarity index 63% rename from docs/how-to-guides/command-line-access/setup.md rename to docs/operate/how-to/command-line-access.md index af552766..013aed8e 100644 --- a/docs/how-to-guides/command-line-access/setup.md +++ b/docs/operate/how-to/command-line-access.md @@ -1,22 +1,25 @@ -# Command line access +--- +tags: [command-line, how-to, operate] +--- + +# Setup command line access This guide shows you how to set up command line tools for accessing NAIS clusters -## Setup -### 0. Prerequisites +## Prerequisites -- [naisdevice](../naisdevice/install.md) installed -- [nais-cli](../nais-cli/install.md) installed +- [naisdevice](../naisdevice/how-to/install.md) installed +- [nais-cli](../cli/how-to/install.md) installed -### 1. Install gcloud +## Install gcloud -Follow Googles instructions on how to install [Gcloud](https://cloud.google.com/sdk/docs/install) for your OS +Follow Googles instructions on how to install [gcloud](https://cloud.google.com/sdk/docs/install) for your OS -### 2. Install kubectl +## Install kubectl Follow the instruction to install [kubectl](https://kubernetes.io/docs/tasks/tools/) for your OS -### 3. Authenticate using gcloud +## Authenticate using gcloud ```shell gcloud auth login --update-adc @@ -24,10 +27,17 @@ gcloud auth login --update-adc This will open your browser. Follow the instructions to authenticate using the email from your organization. + When successfully authenticated, you will be shown "You are now authenitcated with the gcloud CLI!" in your browser. You can now close the browser window. -### 4. Generate kubeconfig file +You will also need to install a plugin in order to authenticate to the Kubernetes clusters: + +```shell +gcloud components install gke-gcloud-auth-plugin +``` + +## Generate kubeconfig file Use nais-cli to generate the kubeconfig file that grants access to the NAIS clusters. @@ -37,7 +47,7 @@ nais kubeconfig A successful run will output how many clusters and where the kubeconfig file is written to. -### 5. Verify access +## Verify access ```shell kubectl --context '' get ns @@ -48,5 +58,3 @@ If you are unsure about which clusters are available, you can list them with: ```shell kubectl config get-clusters ``` - -If you experience any issues, please refer to the [troubleshooting](./troubleshooting.md) guide. diff --git a/docs/how-to-guides/team.md b/docs/operate/how-to/create-team.md similarity index 61% rename from docs/how-to-guides/team.md rename to docs/operate/how-to/create-team.md index 5714bdef..d3a3080b 100644 --- a/docs/how-to-guides/team.md +++ b/docs/operate/how-to/create-team.md @@ -1,18 +1,22 @@ -# Create NAIS team +--- +tags: [team, how-to, operate] +--- + +# Create a NAIS team This how-to guide shows you how to create a NAIS team. -## 0. Prerequisites +## Prerequisites -- [naisdevice installed](./naisdevice/install.md), to be able to access Console. +- [naisdevice installed](../naisdevice/how-to/install.md), to be able to access Console. -## 1. Create your team +## Create your team -1. Open [Console](https://console.<>.cloud.nais.io/) in your browser, and autenticate. +1. Open [Console](https://console.<>.cloud.nais.io/) in your browser, and authenticate. 2. Click on "Create" 3. Choose a team name, add a description of the team and the Slack channel that is mentioned in the prerequisites. 4. Click "Create" Your team will now be created, and you will be the owner. -Read more about what resources are created for your team [here](../explanation/team.md). +Read more about what resources are created for your team [here](../../explanations/team.md). diff --git a/docs/operate/naisdevice/.pages b/docs/operate/naisdevice/.pages new file mode 100644 index 00000000..b43a840a --- /dev/null +++ b/docs/operate/naisdevice/.pages @@ -0,0 +1,4 @@ +nav: +- README.md +- 🎯 How-To: how-to +- ... diff --git a/docs/operate/naisdevice/README.md b/docs/operate/naisdevice/README.md new file mode 100644 index 00000000..2c64fe4d --- /dev/null +++ b/docs/operate/naisdevice/README.md @@ -0,0 +1,20 @@ +--- +tags: [naisdevice, explanation, operate] +--- + +# naisdevice + +naisdevice is a mechanism that lets you connect to services not available on the public internet from your machine. + +Examples of such services are: + +- Access to the NAIS cluster with [kubectl](../how-to/command-line-access.md) +- Applications on [internal domains](../../workloads/reference/environments.md) +- Internal NAIS services such as [Console](../console.md). + +{% if tenant() == "nav" %} + +Before connecting, your machine needs to meet certain requirements. These requirements are enforced by a third-party service called [Kolide](https://kolide.com/) that is installed alongside naisdevice. + +Kolide will notify you through Slack when something is wrong with your machine, and will guide you through the process of fixing it. +{% endif %} diff --git a/tenants/nav/how-to-guides/naisdevice/install.md b/docs/operate/naisdevice/how-to/install.md similarity index 52% rename from tenants/nav/how-to-guides/naisdevice/install.md rename to docs/operate/naisdevice/how-to/install.md index d6c66f31..0f325eb8 100644 --- a/tenants/nav/how-to-guides/naisdevice/install.md +++ b/docs/operate/naisdevice/how-to/install.md @@ -1,20 +1,40 @@ +--- +tags: [naisdevice, how-to] +--- + # Install naisdevice +{% if tenant == "nav" %} + +!!! warning + + To make sure you are using naisdevice as securely as possible, make sure you are a member of the [Slack channel #naisdevice](https://nav-it.slack.com/archives/C013XV66XHB). Important information will be published there. This also where you find us, if you need any help. + ## Prerequisites - [Install the Kolide agent](./install-kolide.md). +!!! note + + On first time connection you will be presented with soft policies (aka. Do's & Don'ts) + +{% endif %} + ## Device-specific installation steps === "macOS" + {% if tenant == "nav" %} + The Kolide agent will be added to your Slack app, and let you know when there are recommended updates or security issues you need to address - and how to address them. They have been vetted by the NAIS team and should be followed to keep your device safe. - 2. [Install Homebrew](https://brew.sh/) unless you already have it. + {% endif %} + + 1. [Install Homebrew](https://brew.sh/) unless you already have it. Homebrew makes it possible to install and maintain apps using the terminal app on your Mac. - 3. Open terminal (Use ` + ` to find `Terminal.app`) and add the nais tap by typing or pasting the text below and press ``. + 1. Open terminal (Use ` + ` to find `Terminal.app`) and add the nais tap by typing or pasting the text below and press ``. Adding the nais tap lets Homebrew know where to get and update files from. Do not worry about where it will be installed, we got you covered. @@ -22,57 +42,98 @@ brew tap nais/tap ``` - 4. When the tap is added, you are ready to install naisdevice, by typing or pasting the following in terminal and press ``. + 1. When the tap is added, you are ready to install naisdevice, by typing or pasting the following in terminal and press ``. + + {% if tenant == "nav" %} ```bash brew install naisdevice ``` - 5. You will be asked for your local device account's password to finish the installation. - 1. The password is not accepted unless you have administrator privileges, so you need to get that first. - 2. If you're running a NAV Mac: Open your `Privileges.app` (Use ` + ` to find the `Privileges.app` and request privileges. When this is done, you can enter your password in terminal. The privileges last 10 minutes. The limited time is due to security reasons, because we know many of us forget to turn it off afterwards. + 1. You will be asked for your local device account's password to finish the installation. + 1. The password is not accepted unless you have administrator privileges, so you need to get that first. + 1. If you're running a NAV Mac: Open your `Privileges.app` (Use ` + ` to find the `Privileges.app` and request privileges. When this is done, you can enter your password in terminal. The privileges last 10 minutes. The limited time is due to security reasons, because we know many of us forget to turn it off afterwards. - 6. Turn on your freshly installed `naisdevice` app. - 1. Use ` + ` to find your `naisdevice.app` and press ``. - 2. Follow the [instructions to connect your _nais_ device](#connect-naisdevice-through-tasksys-tray-icon). + {% else %} - 7. If you need to connect to anything running in K8s cluster, remember to [update your kubeconfig](#connecting-to-nais-clusters) + ```bash + brew install naisdevice-tenant + ``` + + {% endif %} + + 1. You will be asked for your local device account's password to finish the installation. + 1. Turn on your freshly installed `naisdevice` app. + 1. Use ` + ` to find your `naisdevice.app` and press ``. + 1. Follow the [instructions to connect your _nais_ device](#connect-naisdevice-through-tasksys-tray-icon). === "Windows" #### Install using Scoop + {% if tenant == "nav" %} + The Kolide agent will be added to your Slack app, and let you know when there are recommended updates or security issues you need to address - and how to address them. They have been vetted by the NAIS team and should be followed to keep your device safe. + {% endif %} + 1. Install [Scoop](https://scoop.sh) unless you already have it. Scoop makes it possible to install and maintain programs from the command line. 1. Use the following command in the command line to add the nais bucket to let Scoop know where to get and update files from. Do not worry about where it will be installed, we got you covered. + ```powershell scoop bucket add nais https://github.com/nais/scoop-bucket ``` + 1. When the bucket is added, you are ready to install naisdevice, by typing the following in the command line: + + {% if tenant == "nav" %} + ```powershell scoop install naisdevice ``` + + {% else %} + + ```powershell + scoop install naisdevice-tenant + ``` + + {% endif %} + (you will be asked for administrator access to run the installer) - 1. If you need to connect to anything running in K8s cluster, remember to [update your kubeconfig](#connecting-to-nais-clusters) 1. Start _naisdevice_ from the _Start menu_ - ### Manual installation +=== "Manual" + + {% if tenant == "nav" %} - 1. [Install Kolide agent](install-kolide.md). + [Install Kolide agent](install-kolide.md). The Kolide agent will be added to your Slack app, and let you know when there are recommended updates or security issues you need to address - and how to address them. They have been vetted by the NAIS team and should be followed to keep your device safe. - 2. [Download and install naisdevice.exe](https://github.com/nais/device/releases/latest) + [Download and install naisdevice.exe](https://github.com/nais/device/releases/latest) + + {% else %} + + [Download and install naisdevice-tenant.exe](https://github.com/nais/device/releases/latest) + + {% endif %} + (you will be asked for administrator access when you run the installer) - 3. Start _naisdevice_ from the _Start menu_ + + 1. Start _naisdevice_ from the _Start menu_ === "Ubuntu" + !!! warning + + Using Gnome DE on latest Ubuntu LTS - only supported variant atm + 1. Add the nais PPA repo: + ``` NAIS_GPG_KEY="/etc/apt/keyrings/nav_nais_gar.asc" curl -sfSL "https://europe-north1-apt.pkg.dev/doc/repo-signing-key.gpg" | sudo dd of="$NAIS_GPG_KEY" @@ -80,19 +141,48 @@ sudo apt update ``` + **NOTE** curl is not installed in a "fresh" ubuntu: + + ``` + sudo apt install curl + ``` + 1. Install the naisdevice package: + + {% if tenant == "nav" %} + ``` sudo apt install naisdevice ``` + + {% else %} + + ``` + sudo apt install naisdevice-tenant + ``` + + {% endif %} + 1. Turn on your freshly installed `naisdevice` application. - 1. Find `naisdevice` in your application menu, or use the `naisdevice` command in a terminal to start the application. - 2. Follow the [instructions to connect your _nais_ device](#connect-naisdevice-through-tasksys-tray-icon). - 1. Remember to [update your kubeconfig](./install-tenant.md#connecting-to-nais-clusters). + 1. Find `naisdevice` in your application menu, or use the `naisdevice` command in a terminal to start the application. + 2. Follow the [instructions to connect your _nais_ device](#connect-naisdevice-through-tasksys-tray-icon). + +{% if tenant == "nav" %} !!! warning - To make sure you are using naisdevice as securely as possible, make sure you are a member of the [Slack channel #naisdevice](https://nav-it.slack.com/archives/C013XV66XHB). Important information will be published there. This also where you find us, if you need any help. + On first time connection you will be presented with soft policies (aka. Do's & Don'ts) -!!! note +{% endif %} - On first time connection you will be presented with soft policies (aka. Do's & Don'ts) +## Connect naisdevice through task/sys -tray icon + +![A macOS systray exemplifying a red-colored `naisdevice` icon.](../../../assets/naisdevice-systray-icon.svg) + +When you have opened naisdevice, you may be concerned that nothing happened. The little naisdevice icon has appeared in your Systray (where all your small program icons are located - see above picture for how it looks on Mac): + +1. Find your `naisdevice` icon (pictured above - though it should not be red at first attempted connection). +- Can't find the icon? Make sure it is installed (See [macOS](#macos-installation), [Windows](#windows-installation) or [Ubuntu](#ubuntu-installation)) +1. Left-click it and select `Connect`. +1. Left-click the `naisdevice` icon again and click `Connect`. +You might need to allow ~20 seconds to pass before clicking `Connect` turns your `naisdevice` icon green. diff --git a/docs/how-to-guides/naisdevice/troubleshooting.md b/docs/operate/naisdevice/how-to/troubleshooting.md similarity index 91% rename from docs/how-to-guides/naisdevice/troubleshooting.md rename to docs/operate/naisdevice/how-to/troubleshooting.md index ba787633..77a0dcae 100644 --- a/docs/how-to-guides/naisdevice/troubleshooting.md +++ b/docs/operate/naisdevice/how-to/troubleshooting.md @@ -1,4 +1,8 @@ -# Troubleshooting +--- +tags: [naisdevice, how-to] +--- + +# Troubleshooting naisdevice - Browser does not open after you click connect and naisdevice - Restart your default browser. diff --git a/docs/operate/naisdevice/how-to/uninstall.md b/docs/operate/naisdevice/how-to/uninstall.md new file mode 100644 index 00000000..9cfc970f --- /dev/null +++ b/docs/operate/naisdevice/how-to/uninstall.md @@ -0,0 +1,95 @@ +--- +tags: [naisdevice, how-to] +--- + +# Uninstall naisdevice + +## OS-specific Uninstall steps + +{% if tenant == "nav" %} + +### macOS uninstall + +1. Stop and remove Kolide and the related launch mechanisms + ```zsh + sudo /bin/launchctl unload /Library/LaunchDaemons/com.kolide-k2.launcher.plist + sudo /bin/rm -f /Library/LaunchDaemons/com.kolide-k2.launcher.plist + ``` +2. Delete files, configuration and binaries + ```zsh + sudo /bin/rm -rf /usr/local/kolide-k2 + sudo /bin/rm -rf /etc/kolide-k2 + sudo /bin/rm -rf /var/kolide-k2 + ``` +3. Uninstall the naisdevice Homebrew cask + ```bash + brew uninstall --force naisdevice + ``` + +### Windows uninstall + +1. Uninstall _Kolide_ from Apps & Features +2. (Optionally) Uninstall _WireGuard_ from Apps & Features +3. Uninstall naisdevice + * Installed with Scoop + ```powershell + scoop uninstall naisdevice + ``` + * Installed manually + * Uninstall _naisdevice_ from Apps & Features + +### Ubuntu uninstall + +1. Stop and remove Kolide and the related launch mechanisms + ```bash + sudo systemctl stop launcher.kolide-k2.service + sudo systemctl disable launcher.kolide-k2.service + ``` +2. Uninstall Kolide program files + ```bash + sudo apt(-get) remove launcher-kolide-k2 + ``` +3. Delete Kolide files & caches + ```bash + sudo rm -r /{etc,var}/kolide-k2 + ``` +4. Uninstall the naisdevice deb package + ```bash + sudo apt remove naisdevice + ``` + +## OS-agnostic uninstall steps + +When the program has been removed from your device, let an admin know in [#naisdevice](https://nav-it.slack.com/archives/C013XV66XHB) Slack channel. +This is necessary so that the record of your device can be purged from our Kolide systems. + +{% else %} + +### macOS uninstall + +Uninstall the naisdevice Homebrew cask + +```bash +brew uninstall --force naisdevice +``` + +### Windows uninstall + +1. (Optionally) Uninstall _WireGuard_ from Apps & Features +2. Uninstall naisdevice + * Installed with Scoop + ```powershell + scoop uninstall naisdevice + ``` + * Installed manually + * Uninstall _naisdevice_ from Apps & Features + +### Ubuntu uninstall + +Uninstall the naisdevice deb package + +```bash +sudo apt remove naisdevice +``` + +{% endif %} diff --git a/docs/how-to-guides/naisdevice/update.md b/docs/operate/naisdevice/how-to/update.md similarity index 94% rename from docs/how-to-guides/naisdevice/update.md rename to docs/operate/naisdevice/how-to/update.md index dc0ad7c1..bcd95dc4 100644 --- a/docs/how-to-guides/naisdevice/update.md +++ b/docs/operate/naisdevice/how-to/update.md @@ -1,3 +1,7 @@ +--- +tags: [naisdevice, how-to] +--- + # Updating naisdevice === "macOS" diff --git a/docs/persistence/.pages b/docs/persistence/.pages new file mode 100644 index 00000000..49e08c08 --- /dev/null +++ b/docs/persistence/.pages @@ -0,0 +1,4 @@ +nav: +- README.md +- πŸ’‘ Explanations: explanations +- ... diff --git a/docs/persistence/README.md b/docs/persistence/README.md new file mode 100644 index 00000000..393291b8 --- /dev/null +++ b/docs/persistence/README.md @@ -0,0 +1,117 @@ +--- +description: >- + NAIS offers several storage solutions for storing data. This page describes + the different options and how to use them. +tags: [persistence, explanation] +--- + +# Persistent Data Overview + +In this section we will discuss how to work with persistent data in your +applications and the different options available to you. + +Persistent data is data that is stored on disk and survives application +restarts. This is in contrast to ephemeral data which is stored in memory +and is lost when the application is restarted. + +## Responsibilities + +The team is responsible for any data that is stored in the various storage +options that are available through the platform. You can read more in the +[Data Responsibilities](explanations/responsibilities.md) section. + +## Availability + +Some of the storage options are only available from certain environments. Make +sure to check what storage options are available in your environment in the +[Storage Comparison](#storage-comparison) section below. + +## What should I choose? + +Sequence of questions to ask yourself when choosing the right storage option. +Choose wisely. + +```mermaid +graph TD + F[I need caching!] --> REDIS[Redis] + A[I got data!] --> B[Is it structured?] + B --> |Yes| C[Is it events?] + B --> |No| D[Is it files?] + C --> |Yes| Kafka + C --> |No| E[Is it analytical?] + D --> |Yes| GCS[Cloud Storage] + D --> |No| Opensearch[OpenSearch] + E --> |Yes| GBQ[BigQuery] + E --> |No| GCSQL[Cloud SQL] + + click REDIS "#redis" + click GBQ "#bigquery" + click GCS "#cloud-storage-buckets" + click GCSQL "#cloud-sql" + click Kafka "#kafka" + click Opensearch "#opensearch" +``` + +## Storage Comparison + +Below is a list of the different storage options available to you. + +| Name | Type | Recommendation | Availability | Backup | +|-----------------------------------------|-------------|:--------------:|:------------:|:------:| +| [Kafka](#kafka) | Streaming | βœ… | All | Yes* | +| [Cloud Storage](#cloud-storage-buckets) | Object | βœ… | GCP | Yes* | +| [Cloud SQL](#cloud-sql) | Relational | βœ… | GCP | Yes | +| [BigQuery](#bigquery) | Relational | βœ… | GCP | Yes* | +| [OpenSearch](#opensearch) | Document | βœ… | GCP | Yes | +| [Redis](#redis) | Key/Value | βœ… | GCP | Yes | + +\* Data is highly available and fault-tolerant but not backed up if deleted by +mistake. + +## Kafka + +Kafka is a streaming platform that is used for storing and processing data. It +is a very powerful tool that can be used for a wide variety of use cases. It is +also a very complex tool that requires a lot of knowledge to use effectively. + +[:bulb: Learn more about Kafka](./kafka/README.md) + +## Cloud Storage (Buckets) + +Cloud Storage is a service that provides object storage. It is a very simple +service that is easy to use and provides a lot of flexibility. It is a good +choice for storing data that is not relational in nature. + +[:bulb: Learn more about Cloud Storage](./buckets/README.md) + +## Cloud SQL + +Cloud SQL is a PostgreSQL relational database service that is provided by Google +Cloud Platform. It is a good choice for storing data that is relational in +nature. + +[:bulb: Learn more about Cloud SQL](./postgres/README.md) + +## BigQuery + +BigQuery is a service that provides a relational database that is optimized for +analytical workloads. It is a good choice for storing data that is relational in +nature. + +[:bulb: Learn more about Google BigQuery](./bigquery/README.md) + +## OpenSearch + +OpenSearch is a document database that is used for storing and searching data. +It is a good choice for storing data that is not relational in nature. +OpenSearch offers a drop-in replacement for Elasticsearch. + +[:bulb: Learn more about OpenSearch](./opensearch/README.md) + +## Redis + +Redis is a key value database that is used for storing and querying data. It is +a good choice for storing data that is not relational in nature and often used +for caching. + +[:bulb: Learn more about Redis](./redis/README.md) diff --git a/docs/persistence/bigquery/.pages b/docs/persistence/bigquery/.pages new file mode 100644 index 00000000..99efe087 --- /dev/null +++ b/docs/persistence/bigquery/.pages @@ -0,0 +1,5 @@ +title: BigQuery +nav: +- README.md +- 🎯 How-To: how-to +- ... diff --git a/docs/explanation/database/bigquery.md b/docs/persistence/bigquery/README.md similarity index 78% rename from docs/explanation/database/bigquery.md rename to docs/persistence/bigquery/README.md index 141df7a5..637d8d07 100644 --- a/docs/explanation/database/bigquery.md +++ b/docs/persistence/bigquery/README.md @@ -1,3 +1,7 @@ +--- +tags: [persistence, bigquery, explanation, services] +--- + # Google Cloud BigQuery Dataset Google Cloud BigQuery is a service that provides a relational database that is optimized for analytical workloads. It is a good choice for storing data that is relational in nature. @@ -8,17 +12,17 @@ started with BigQuery for your applications. # NAIS Application yaml manifest options -Full documentation of all available options can be found over at: [`spec.gcp.bigQueryDatasets[]`](../../reference/application-spec.md#gcpbigquerydatasets). +Full documentation of all available options can be found over at: [`spec.gcp.bigQueryDatasets[]`](../../workloads/application/reference/application-spec.md#gcpbigquerydatasets). Example of an application using a `nais.yaml` provisioned BigQuery Dataset can be found here: [testapp](https://github.com/nais/testapp/blob/master/pkg/bigquery/bigquery.go). ## Caveats to be aware of === "Automatic Deletion" - Once a BigQuery Dataset is provisioned, it will not be automatically deleted - unless one explicitly sets [`spec.gcp.bigQueryDatasets[].cascadingDelete`](../../reference/application-spec.md#gcpbigquerydatasetscascadingdelete) to `true`. + Once a BigQuery Dataset is provisioned, it will not be automatically deleted - unless one explicitly sets [`spec.gcp.bigQueryDatasets[].cascadingDelete`](../../workloads/application/reference/application-spec.md#gcpbigquerydatasetscascadingdelete) to `true`. Clean up is done by deleting application resource and deleting the BigQuery instance directly in [console.cloud.google.com](https://console.cloud.google.com/bigquery).
- When there exist no tables in the specified BigQuery Dataset, deleting the "nais application" will delete the whole BigQuery Dataset, even if [`spec.gcp.bigQueryDatasets[].cascadingDelete`](../../reference/application-spec.md#gcpbigquerydatasetscascadingdelete) is set to `false`. + When there exist no tables in the specified BigQuery Dataset, deleting the "nais application" will delete the whole BigQuery Dataset, even if [`spec.gcp.bigQueryDatasets[].cascadingDelete`](../../workloads/application/reference/application-spec.md#gcpbigquerydatasetscascadingdelete) is set to `false`. === "Unique names" The name of your Dataset must be unique within your team's GCP project. === "Updates/Immutability" @@ -30,4 +34,4 @@ Example of an application using a `nais.yaml` provisioned BigQuery Dataset can b ## Example with all configuration options -See [full example](../../reference/application-example.md). \ No newline at end of file +See [full example](../../workloads/application/reference/application-example.md). diff --git a/docs/how-to-guides/persistence/bigquery/connect.md b/docs/persistence/bigquery/how-to/connect.md similarity index 92% rename from docs/how-to-guides/persistence/bigquery/connect.md rename to docs/persistence/bigquery/how-to/connect.md index 069bff53..df249431 100644 --- a/docs/how-to-guides/persistence/bigquery/connect.md +++ b/docs/persistence/bigquery/how-to/connect.md @@ -1,3 +1,7 @@ +--- +tags: [how-to, bigquery] +--- + # Using BigQuery from your application When connecting your BigQuery client you need to specify the project ID and the dataset ID. diff --git a/docs/how-to-guides/persistence/bigquery/create.md b/docs/persistence/bigquery/how-to/create.md similarity index 76% rename from docs/how-to-guides/persistence/bigquery/create.md rename to docs/persistence/bigquery/how-to/create.md index c036e376..253cd773 100644 --- a/docs/how-to-guides/persistence/bigquery/create.md +++ b/docs/persistence/bigquery/how-to/create.md @@ -1,6 +1,10 @@ +--- +tags: [how-to, bigquery] +--- + # Create an instance of BigQuery -Below you'll se a minimal working example for a NAIS Application manifest. +Below is a minimal working example for a NAIS Application manifest. ## 1. Create dataset ???+ note ".nais/app.yaml" diff --git a/docs/persistence/buckets/.pages b/docs/persistence/buckets/.pages new file mode 100644 index 00000000..32705eb9 --- /dev/null +++ b/docs/persistence/buckets/.pages @@ -0,0 +1,5 @@ +nav: +- README.md +- 🎯 How-To: how-to +- πŸ“š Reference: reference.md +- ... diff --git a/docs/persistence/buckets/README.md b/docs/persistence/buckets/README.md new file mode 100644 index 00000000..ee98686e --- /dev/null +++ b/docs/persistence/buckets/README.md @@ -0,0 +1,10 @@ +--- +tags: [bucket, services, explanation] +--- + +# Buckets + +A bucket is a storage container for objects. +Objects are files that contain data, such as documents, images, videos, and application code. + +NAIS supports provisioning and managing buckets in Google Cloud Storage (GCS) for use by your applications. diff --git a/docs/how-to-guides/persistence/buckets/create.md b/docs/persistence/buckets/how-to/create.md similarity index 61% rename from docs/how-to-guides/persistence/buckets/create.md rename to docs/persistence/buckets/how-to/create.md index 22d1694a..68b599ce 100644 --- a/docs/how-to-guides/persistence/buckets/create.md +++ b/docs/persistence/buckets/how-to/create.md @@ -1,12 +1,16 @@ -# Create +--- +tags: [how-to, bucket] +--- + +# Create a bucket This guide will show you how to create a Google Cloud Storage bucket. -## 0. Add the bucket to the NAIS application manifest +## Add the bucket to the NAIS application manifest You create the bucket through the NAIS application manifest. -!!!+ note "Naming" +!!! warning "Use a globally unique name" Bucket names must be globally unique across the entire Google infrastructure. @@ -29,11 +33,11 @@ spec: withState: ANY ``` -`retentionPeriodDays` and `lifecycleCondition` are for neccessary for [backup](../../../reference/bucket-backup.md). +`retentionPeriodDays` and `lifecycleCondition` are for necessary for [backup](../reference.md). -## 1. Deploy your manifest +## Deploy your manifest -Deploy your manifest either using [NAIS deploy action](../../github-action.md), or manually: +Deploy your manifest either using [NAIS deploy action](../../../build/how-to/build-and-deploy.md), or manually: ```bash kubectl apply -f diff --git a/docs/how-to-guides/persistence/buckets/delete.md b/docs/persistence/buckets/how-to/delete.md similarity index 89% rename from docs/how-to-guides/persistence/buckets/delete.md rename to docs/persistence/buckets/how-to/delete.md index 26f762a3..4ab602c8 100644 --- a/docs/how-to-guides/persistence/buckets/delete.md +++ b/docs/persistence/buckets/how-to/delete.md @@ -1,8 +1,11 @@ +--- +tags: [bucket, how-to] +--- # Deleting a bucket Delete unused buckets to avoid incurring unnecessary costs. A bucket is deleted by enabling cascading deletion, and deleting the application. -## 1. Enable cascading/automatic deletion +## Enable cascading/automatic deletion For deletion of the application to automatically delete the bucket, set `cascadingDelete` to `true` in your NAIS application spesification. Don't worry, the bucket won't be deleted if it contains files. @@ -25,7 +28,7 @@ spec: numNewerVersions: 2 withState: ANY ``` -## 2. Delete your application +## Delete your application Delete your application resource. diff --git a/docs/reference/bucket-backup.md b/docs/persistence/buckets/reference.md similarity index 91% rename from docs/reference/bucket-backup.md rename to docs/persistence/buckets/reference.md index 990f2e18..d290b10a 100644 --- a/docs/reference/bucket-backup.md +++ b/docs/persistence/buckets/reference.md @@ -1,8 +1,14 @@ -# Backup of a bucket +--- +tags: [reference, bucket] +--- + +# Bucket reference + +## Backup of a bucket There is no automatic backup enabled for buckets. I.e. the files can not be restored in the event of accidental deletion or storage system failure. -## Specification +### Specification * `retentionPeriodDays` is set in number of days, if not set; no retention policy will be set and files can be deleted by application or manually. diff --git a/docs/persistence/explanations/responsibilities.md b/docs/persistence/explanations/responsibilities.md new file mode 100644 index 00000000..5d32873b --- /dev/null +++ b/docs/persistence/explanations/responsibilities.md @@ -0,0 +1,61 @@ +--- +tags: [explanations, persistence] +description: >- + This page aims to clarify the responsibilities as relates to data storage + using NAIS and GCP. Depending on which infrastructure the data is stored on, + the responsibilities look slightly different. +--- + +# Responsibilities + +It is important to understand the responsibilities of the different parties involved when working with data in NAIS. This page aims to clarify the responsibilities as relates to data storage on-prem and in GCP. Depending on which infrastructure the data is stored on, the responsibilites look slightly different. + +## The Platform + +The platform does not manage the underlying infrastructure or run the data storage service provided by the platform. +These are provided by NAV, Google or Aiven. +NAIS is responsible for setting up the infrastructure and data storage service according to the specifications provided by the application. + +The platform team is responsible for the following: + +* Provisioning and maintaining underlying infrastructure +* Tooling and automation to make it easy to use the platform +* Providing documentation and support for the platform + +The platform team is **not** responsible for the application itself, not the data stored in the provided data storage services. + +??? note "List of data processors" + +{% if tenant() == "nav" %} + | Infrastructure | Data processor | + |----------------|----------------| + | On-premise | NAV (ITIP) | + | Cloud Storage | Google | + | Cloud SQL | Google | + | BigQuery | Google | + | Kafka | Aiven | + | OpenSearch | Aiven | +{% else %} + | Infrastructure | Data processor | + |----------------|----------------| + | Cloud Storage | Google | + | Cloud SQL | Google | + | BigQuery | Google | + | Kafka | Aiven | + | OpenSearch | Aiven | +{% endif %} + +## The Team + +At the end of the day, the team is responsible for its own data and how it is managed. This includes compliance with data policies (e.g. GDPR or archiving), ensuring disaster recovery (aided by tooling and interfaces supplied by the platform) and daily operations. + +### Team Checklist for Data Storage + +Here is a simple checklist for what the teams should think about related to how and where the data is stored: + +{% if tenant() == "nav" %} +* [x] Update [Behandlingskatalogen](https://behandlingskatalog.nais.adeo.no) where data is stored. +{% endif %} +* [x] Is the data storage in compliance with data policies (GDPR, PII, etc.)? +* [x] What is the SLA for the data storage? +* [x] What is the backup strategy for the data storage? diff --git a/docs/persistence/kafka/.pages b/docs/persistence/kafka/.pages new file mode 100644 index 00000000..f092fbf6 --- /dev/null +++ b/docs/persistence/kafka/.pages @@ -0,0 +1,5 @@ +nav: +- README.md +- 🎯 How-To: how-to +- πŸ“š Reference: reference +- ... diff --git a/docs/explanation/kafka.md b/docs/persistence/kafka/README.md similarity index 89% rename from docs/explanation/kafka.md rename to docs/persistence/kafka/README.md index a5fca41d..891ccbdc 100644 --- a/docs/explanation/kafka.md +++ b/docs/persistence/kafka/README.md @@ -1,5 +1,29 @@ +--- +description: >- + Kafka is a distributed streaming platform that can be used to publish and + subscribe to streams of records. It is a good alternative to synchronous + communication between services if you need to decouple services. +tags: [kafka, explanation, persistence, services] +--- + # Kafka +NAIS offers Kafka as a managed service through Aiven. + +Start using Kafka by [creating a `Topic` resource](how-to/create.md) in one of our Kubernetes clusters. + +A `Topic` belongs to one of the Kafka _pools_. +A pool is a highly available, replicated Kafka cluster running at Aiven. +After the topic is created, relevant users are added to the topic's access control list (ACL). + +To get started with Kafka in your application, see [accessing topics from an application](how-to/access.md). + +!!! note "Backups and recovery" + + Kafka as a system is highly durable, and is designed to be able to keep your data safe in the event of a failure. + This requires a properly configured replication factor for your topic, and that your clients use the appropriate strategy when sending messages and committing offsets. + Even so, our recommendation is that Kafka should not be the master of your data, and you should have the ability to restore your data from some other system. + ## What happens on deploy? When you deploy an application that requests access to Kafka, Naiserator will create an `AivenApplication` resource in the cluster. diff --git a/docs/how-to-guides/persistence/kafka/access.md b/docs/persistence/kafka/how-to/access.md similarity index 69% rename from docs/how-to-guides/persistence/kafka/access.md rename to docs/persistence/kafka/how-to/access.md index b41f4d92..d9f14b5f 100644 --- a/docs/how-to-guides/persistence/kafka/access.md +++ b/docs/persistence/kafka/how-to/access.md @@ -1,12 +1,16 @@ +--- +tags: [how-to, kafka] +--- + # Accessing topics from an application This guide shows you how to access Kafka topics from your application. -## 0. Prerequisites +## Prerequisites -You need an existing topic to access. See [Create a Kafka topic](./create.md) for how to create a topic. +You need an existing topic to access. See [Create a Kafka topic](create.md) for how to create a topic. -## 1. Enable access to the relevant pool in your workload definition +## Enable access to the relevant pool in your workload definition ???+ note ".nais/app.yaml" @@ -23,11 +27,11 @@ You need an existing topic to access. See [Create a Kafka topic](./create.md) fo pool: # TODO: link to available tenant pools ``` -## 2. Grant access to the topic +## Grant access to the topic The owner of the topic must [grant your application access to the topic](manage-acl.md). -## 3. Configure your application +## Configure your application Aiven has written several articles on how to configure your application. We use SSL, so ignore the SASL-SSL examples: @@ -37,12 +41,13 @@ We use SSL, so ignore the SASL-SSL examples: - [Node.js](https://docs.aiven.io/docs/products/kafka/howto/connect-with-nodejs.html) - [Go](https://docs.aiven.io/docs/products/kafka/howto/connect-with-go.html) -For all available fields and configuration options, see the [kafka reference](../../../reference/kafka.md). -We recommend following the [application design guidelines](../../../explanation/kafka.md#application-design-guidelines) for how to configure your application. +For all available environment variables, see the [reference](../reference/environment-variables.md). + +We recommend following the [application design guidelines](../README.md#application-design-guidelines) for how to configure your application. -## 3. Apply the application +## Apply the application === "Automatically" - Add the file to your application repository to deploy with [NAIS github action](../../github-action.md). + Add the file to your application repository to deploy with [NAIS github action](../../../build/how-to/build-and-deploy.md). === "Manually" ```bash kubectl apply -f ./nais/app.yaml --namespace= --context= diff --git a/docs/how-to-guides/persistence/kafka/create.md b/docs/persistence/kafka/how-to/create.md similarity index 71% rename from docs/how-to-guides/persistence/kafka/create.md rename to docs/persistence/kafka/how-to/create.md index 28e3cfcf..cb8457c7 100644 --- a/docs/how-to-guides/persistence/kafka/create.md +++ b/docs/persistence/kafka/how-to/create.md @@ -1,7 +1,11 @@ +--- +tags: [how-to, kafka] +--- + # Create a Kafka topic This guide will show you how to create a Kafka topic -## 0. Creating topics +## Creating topics ???+ note ".nais/topic.yaml" ```yaml hl_lines="4-5 7 9 11-14" @@ -19,14 +23,14 @@ This guide will show you how to create a Kafka topic application: access: readwrite # read, write, readwrite ``` -See the [Kafka topic reference](../../../reference/kafka-topic-spec.md) for a complete list of available options. +See the [Kafka topic reference](../reference/kafka-topic-spec.md) for a complete list of available options. -## 1. Grant access to the topic for other applications (optional) +## Grant access to the topic for other applications (optional) See [manage access](manage-acl.md) for how to grant access to your topic. -## 2. Apply the Topic resource +## Apply the Topic resource === "Automatically" - Add the file to your application repository to deploy with [NAIS github action](../../github-action.md). + Add the file to your application repository to deploy with [NAIS github action](../../../build/how-to/build-and-deploy.md). === "Manually" ```bash kubectl apply -f ./nais/topic.yaml --namespace= --context= diff --git a/docs/how-to-guides/persistence/kafka/delete.md b/docs/persistence/kafka/how-to/delete.md similarity index 85% rename from docs/how-to-guides/persistence/kafka/delete.md rename to docs/persistence/kafka/how-to/delete.md index fa577f26..bf996399 100644 --- a/docs/how-to-guides/persistence/kafka/delete.md +++ b/docs/persistence/kafka/how-to/delete.md @@ -1,9 +1,13 @@ +--- +tags: [how-to, kafka] +--- + # Delete Kafka topic and data !!! warning Permanent deletes are irreversible. Enable this feature only as a step to completely remove your data. -## 0. Enable data deletion +## Enable data deletion When a `Topic` resource is deleted from a Kubernetes cluster, the Kafka topic is still retained, and the data kept intact. If you need to remove data and start from scratch, you must add the following annotation to your `Topic` resource: ???+ note ".nais/topic.yaml" @@ -18,16 +22,16 @@ When a `Topic` resource is deleted from a Kubernetes cluster, the Kafka topic is ``` When this annotation is in place, deleting the topic resource from Kubernetes will also delete the Kafka topic and all of its data. -## 1. Apply the Topic resource +## Apply the Topic resource === "Automatically" - Add the file to your application repository to deploy with [NAIS github action](../../github-action.md). + Add the file to your application repository to deploy with [NAIS github action](../../../build/how-to/build-and-deploy.md). === "Manually" ```bash kubectl apply -f ./nais/topic.yaml --namespace= --context= ``` -## 2. Delete the topic resource +## Delete the topic resource ```bash kubectl delete -f ./nais/topic.yaml --namespace= --context= ``` diff --git a/docs/how-to-guides/persistence/kafka/internal.md b/docs/persistence/kafka/how-to/internal.md similarity index 82% rename from docs/how-to-guides/persistence/kafka/internal.md rename to docs/persistence/kafka/how-to/internal.md index db32c57d..6bfd5615 100644 --- a/docs/how-to-guides/persistence/kafka/internal.md +++ b/docs/persistence/kafka/how-to/internal.md @@ -1,7 +1,11 @@ +--- +tags: [how-to, kafka] +--- + # Using Kafka Streams with internal topics This guide will show you how to use Kafka Streams with internal topics. -## 1. Enable Kafka Streams in your application +## Enable Kafka Streams in your application ???+ note ".nais/app.yaml" ```yaml hl_lines="11" @@ -17,13 +21,13 @@ This guide will show you how to use Kafka Streams with internal topics. pool: # TODO: link to available tenant pools streams: true ``` -## 2. Configure your application +## Configure your application When you do this you **must** configure Kafka Streams by setting the property `application.id` to a value that starts with the value of the env var `KAFKA_STREAMS_APPLICATION_ID`, which will be injected into your pod automatically. -## 3. Apply the application +## Apply the application === "Automatically" - Add the file to your application repository to deploy with [NAIS github action](../../github-action.md). + Add the file to your application repository to deploy with [NAIS github action](../../../build/how-to/build-and-deploy.md). === "Manually" ```bash kubectl apply -f ./nais/app.yaml --namespace= --context= diff --git a/docs/how-to-guides/persistence/kafka/manage-acl.md b/docs/persistence/kafka/how-to/manage-acl.md similarity index 85% rename from docs/how-to-guides/persistence/kafka/manage-acl.md rename to docs/persistence/kafka/how-to/manage-acl.md index be34e9ac..9f25d4c5 100644 --- a/docs/how-to-guides/persistence/kafka/manage-acl.md +++ b/docs/persistence/kafka/how-to/manage-acl.md @@ -1,18 +1,22 @@ +--- +tags: [how-to, kafka] +--- + # Manage access This guide will show you how to manage access to your topic -## 0. Prerequisites +## Prerequisites -- [An existing topic](./create.md) to manage access to. +- [An existing topic](create.md) to manage access to. -## 1. Add ACLs to your topic +## Add ACLs to your topic !!! info It is possible to use simple wildcards (`*`) in both team and application names, which matches any character any number of times. Be aware that due to the way ACLs are generated and length limits, the ends of long names can be cut, eliminating any wildcards at the end. -Example of varoius ACLs: +Example of various ACLs: ???+ note ".nais/topic.yaml" @@ -44,9 +48,9 @@ Example of varoius ACLs: ... ``` -## 2. Apply the Topic resource +## Apply the Topic resource === "Automatically" - Add the file to your application repository to deploy with [NAIS github action](../../github-action.md). + Add the file to your application repository to deploy with [NAIS github action](../../../build/how-to/build-and-deploy.md). === "Manually" ```bash kubectl apply -f ./nais/topic.yaml --namespace= --context= diff --git a/docs/how-to-guides/persistence/kafka/monitoring.md b/docs/persistence/kafka/how-to/monitoring.md similarity index 98% rename from docs/how-to-guides/persistence/kafka/monitoring.md rename to docs/persistence/kafka/how-to/monitoring.md index c4dd1556..7c8b7b97 100644 --- a/docs/how-to-guides/persistence/kafka/monitoring.md +++ b/docs/persistence/kafka/how-to/monitoring.md @@ -1,3 +1,7 @@ +--- +tags: [how-to, kafka] +--- + # Kafka metrics This guide will show you how to monitor your Kafka topics with Grafana. diff --git a/docs/how-to-guides/persistence/kafka/remove-access.md b/docs/persistence/kafka/how-to/remove-access.md similarity index 78% rename from docs/how-to-guides/persistence/kafka/remove-access.md rename to docs/persistence/kafka/how-to/remove-access.md index 5f64b953..a73b6841 100644 --- a/docs/how-to-guides/persistence/kafka/remove-access.md +++ b/docs/persistence/kafka/how-to/remove-access.md @@ -1,10 +1,14 @@ +--- +tags: [how-to, kafka] +--- + # Remove access to Kafka This guide will show you how to remove your application's access to a Kafka topic. -## 1. Remove ACLs from the topic +## Remove ACLs from the topic [Remove the ACL](manage-acl.md) that grants your application access to the topic. -## 2. Remove the kafka resource from your application +## Remove the kafka resource from your application ???+ note ".nais/app.yaml" ```yaml hl_lines="9-10" @@ -20,9 +24,9 @@ This guide will show you how to remove your application's access to a Kafka topi pool: # TODO: link to available tenant pools ``` -## 3. Apply the application +## Apply the application === "Automatically" - Add the file to your application repository to deploy with [NAIS github action](../../github-action.md). + Add the file to your application repository to deploy with [NAIS github action](../../../build/how-to/build-and-deploy.md). === "Manually" ```bash kubectl apply -f ./nais/app.yaml --namespace= --context= diff --git a/docs/how-to-guides/persistence/kafka/schema-operations.md b/docs/persistence/kafka/how-to/schema-operations.md similarity index 98% rename from docs/how-to-guides/persistence/kafka/schema-operations.md rename to docs/persistence/kafka/how-to/schema-operations.md index df94a339..ccd3a9e3 100644 --- a/docs/how-to-guides/persistence/kafka/schema-operations.md +++ b/docs/persistence/kafka/how-to/schema-operations.md @@ -1,3 +1,7 @@ +--- +tags: [how-to, kafka] +--- + # Avro and schema This guide will show you how to do various schema operations on your Kafka topics. diff --git a/docs/reference/kafka.md b/docs/persistence/kafka/reference/environment-variables.md similarity index 56% rename from docs/reference/kafka.md rename to docs/persistence/kafka/reference/environment-variables.md index 01449918..152b06f7 100644 --- a/docs/reference/kafka.md +++ b/docs/persistence/kafka/reference/environment-variables.md @@ -1,11 +1,13 @@ -# Kafka +--- +tags: [kafka, reference] +--- -## Environment variables for Kafka +# Environment variables for Kafka These variables are made available to your application when Kafka is enabled. | Variable name | Description | -| :------------------------------- | :------------------------------------------------------------------------- | +|:---------------------------------|:---------------------------------------------------------------------------| | `KAFKA_BROKERS` | Comma-separated list of HOST:PORT pairs to Kafka brokers | | `KAFKA_SCHEMA_REGISTRY` | URL to schema registry | | `KAFKA_SCHEMA_REGISTRY_USER` | Username to use with schema registry | @@ -20,19 +22,3 @@ These variables are made available to your application when Kafka is enabled. | `KAFKA_KEYSTORE_PATH` | PKCS\#12 keystore for use with Java clients, as file | | `KAFKA_TRUSTSTORE_PATH` | JKS truststore for use with Java clients, as file | | `AIVEN_SECRET_UPDATED` | A timestamp of when the secret was created | - - -## Authentication and authorization - -The NAIS platform will generate new credentials when your applications is deployed. Kafka requires TLS client certificates for authentication. Make sure your Kafka and/or TLS library can do client certificate authentication, and that you can specify a custom CA certificate for server validation. - -## Readiness and liveness - -Making proper use of liveness and readiness probes can help with many situations. -If producing or consuming Kafka messages are a vital part of your application, you should consider failing one or both probes if you have trouble with Kafka connectivity. -Depending on your application, failing liveness might be the proper course of action. -This will make sure your application is restarted when it is experiencing problems, which might help. - -In other cases, failing just the readiness probe will allow your application to continue running, attempting to move forward without being killed. -Failing readiness will be most helpful during deployment, where the old instances will keep running until the new are ready. -If the new instances are not able to connect to Kafka, keeping the old ones until the problem is resolved will allow your application to continue working. diff --git a/docs/reference/kafka-topic-example.md b/docs/persistence/kafka/reference/kafka-topic-example.md similarity index 100% rename from docs/reference/kafka-topic-example.md rename to docs/persistence/kafka/reference/kafka-topic-example.md diff --git a/docs/reference/kafka-topic-spec.md b/docs/persistence/kafka/reference/kafka-topic-spec.md similarity index 100% rename from docs/reference/kafka-topic-spec.md rename to docs/persistence/kafka/reference/kafka-topic-spec.md diff --git a/docs/persistence/opensearch/.pages b/docs/persistence/opensearch/.pages new file mode 100644 index 00000000..44832e4f --- /dev/null +++ b/docs/persistence/opensearch/.pages @@ -0,0 +1,7 @@ +title: OpenSearch + +nav: +- README.md +- 🎯 How-To: how-to +- πŸ“š Reference: reference.md +- ... diff --git a/docs/how-to-guides/persistence/opensearch/README.md b/docs/persistence/opensearch/README.md similarity index 64% rename from docs/how-to-guides/persistence/opensearch/README.md rename to docs/persistence/opensearch/README.md index d0e73f9b..7477417f 100644 --- a/docs/how-to-guides/persistence/opensearch/README.md +++ b/docs/persistence/opensearch/README.md @@ -1,5 +1,11 @@ +--- +tags: [opensearch, explanation, persistence, services] +--- + +# OpenSearch + OpenSearch is a fork of Elasticsearch that is maintained by Amazon. It is a drop-in replacement for Elasticsearch, and is fully compatible with the Elasticsearch API. It is a community-driven project that is open source and free to use. OpenSearch is a distributed, RESTful search and analytics engine capable of solving a growing number of use cases. It is a good choice for storing data that is not relational in nature. -NAIS offers OpenSearch via Aiven. Aiven OpenSearch can be used by applications in all environments, but must be defined in a GCP cluste +NAIS offers OpenSearch via [Aiven](https://aiven.io/). Aiven OpenSearch can be used by applications in all environments, but must be *defined* in a GCP cluster. diff --git a/docs/how-to-guides/persistence/opensearch/create.md b/docs/persistence/opensearch/how-to/create.md similarity index 90% rename from docs/how-to-guides/persistence/opensearch/create.md rename to docs/persistence/opensearch/how-to/create.md index cee2af01..22859d04 100644 --- a/docs/how-to-guides/persistence/opensearch/create.md +++ b/docs/persistence/opensearch/how-to/create.md @@ -1,11 +1,13 @@ --- ---- +tags: [how-to, opensearch] description: >- NAIS provides managed search index services through OpenSearch as a drop-in replacement for Elasticsearch. --- -Explicitly creating a OpenSearch instance is done by adding a OpenSearch resource to your namespace with detailed configuration in a GCP cluster. In your `Application` or `Naisjob` specifications, you specify an instance and access. +# Create an OpenSearch instance + +Explicitly creating an OpenSearch instance is done by adding a OpenSearch resource to your namespace with detailed configuration in a GCP cluster. In your `Application` or `Naisjob` specifications, you specify an instance and access. The minimal OpenSearch resource looks like this: diff --git a/docs/reference/opensearch.md b/docs/persistence/opensearch/reference.md similarity index 88% rename from docs/reference/opensearch.md rename to docs/persistence/opensearch/reference.md index 41fb3f5b..4870e87b 100644 --- a/docs/reference/opensearch.md +++ b/docs/persistence/opensearch/reference.md @@ -1,12 +1,8 @@ --- -tags: - - opensearch +tags: [opensearch, reference] --- -# Opensearch - -Nais provides OpenSearch by way of Aiven via their Aiven Operator. - +# OpenSearch reference ## Configuration options diff --git a/docs/how-to-guides/persistence/postgres/README.md b/docs/persistence/postgres/README.md similarity index 89% rename from docs/how-to-guides/persistence/postgres/README.md rename to docs/persistence/postgres/README.md index d661899d..946001cb 100644 --- a/docs/how-to-guides/persistence/postgres/README.md +++ b/docs/persistence/postgres/README.md @@ -1,3 +1,7 @@ +--- +tags: [explanation, persistence, services] +--- + # Google Cloud SQL / PostgreSQL !!! info @@ -6,7 +10,7 @@ PostgreSQL is a relational database service that is provided by Google Cloud Platform. It is a good choice for storing data that is relational in nature. -You can provision and configure [Postgres](https://www.postgresql.org/) through your [`application manifest`](../../../reference/application-spec.md). +You can provision and configure [Postgres](https://www.postgresql.org/) through your [`application manifest`](../../workloads/application/reference/application-spec.md). The database is provisioned into the teams own project in GCP. Here the team has full access to view logs, create and restore backups and other administrative database tasks. @@ -14,7 +18,7 @@ When you deploy your application with database config, NAIS will ensure the data The Database instance takes a few minutes to be created, so your app will not be able to connect to right away. This only applies to the first time deploy. -Below is an example of the minimal configuration needed. See all configuration options in the [application manifest reference](../../../reference/application-spec.md#gcpsqlinstances). +Below is an example of the minimal configuration needed. See all configuration options in the [application manifest reference](../../workloads/application/reference/application-spec.md#gcpsqlinstances). ```yaml ... @@ -33,7 +37,8 @@ spec: ``` !!! important "Choosing the right tier for production" - By default, the database server is `db-f1-micro` which has 1 vCPU, 614 MB RAM and 10GB of SSD storage with no automatic storage increase. Shared CPU machine types (`db-f1-micro` and `db-g1-small`) are **NOT** covered by the [Cloud SQL SLA](https://cloud.google.com/sql/sla). Consider [changing](../../../reference/application-spec.md#gcpsqlinstancestier) to the `db-custom-CPU-RAM` tier for your production databases. Please also note that exhausting disk and/or CPU with automatic increase disabled is [not](https://cloud.google.com/sql/docs/postgres/operational-guidelines) covered by the SLA. + + By default, the database server is `db-f1-micro` which has 1 vCPU, 614 MB RAM and 10GB of SSD storage with no automatic storage increase. Shared CPU machine types (`db-f1-micro` and `db-g1-small`) are **NOT** covered by the [Cloud SQL SLA](https://cloud.google.com/sql/sla). Consider [changing](../../workloads/application/reference/application-spec.md#gcpsqlinstancestier) to the `db-custom-CPU-RAM` tier for your production databases. Please also note that exhausting disk and/or CPU with automatic increase disabled is [not](https://cloud.google.com/sql/docs/postgres/operational-guidelines) covered by the SLA. ## Configuration @@ -65,7 +70,7 @@ The prefix `NAIS_DATABASE_MYAPP_MYDB` is automatically generated from the instan Note that if you change your application name, database name or envVarPrefix, and then change it later, you have to manually [reset database credentials](#reset-database-credentials). -[^1]: jdbc url can be generated for instances without private IP by using [nais cli](https://github.com/nais/cli) to rotate the password. +[^1]: jdbc url can be generated for instances without private IP by using [nais-cli] to rotate the password. ### Database flags @@ -77,7 +82,7 @@ the flags available are listed here: [Google Cloud SQL supported flags](https:// This listing specifies what value types are expected, which ranges are allowed and if a restart is required. !!! info - The value is always required to be a string in [`nais.yaml`](../../../reference/application-spec.md). + The value is always required to be a string in [`nais.yaml`](../../workloads/application/reference/application-spec.md). Example of setting database flags: ```yaml @@ -110,11 +115,13 @@ For further reading see [Google Cloud SQL Query Insights](https://cloud.google.c Data is available for seven days, increasing this will incur extra cost. ### Maintenance window -Google will automatically perform upgrades, fix bugs and apply security patches to prevent exploits. Your application should be able to handle occasional downtime as this maintenance is performed. [Read more on maintenance windows](https://cloud.google.com/sql/docs/postgres/maintenance). NAIS does not configure the maintenance window, but this can be set up in the application spec: [`nais.yaml`](../../../reference/application-spec.md#gcpsqlinstances). + +Google will automatically perform upgrades, fix bugs and apply security patches to prevent exploits. Your application should be able to handle occasional downtime as this maintenance is performed. [Read more on maintenance windows](https://cloud.google.com/sql/docs/postgres/maintenance). NAIS does not configure the maintenance window, but this can be set up in the application spec: [`nais.yaml`](../../workloads/application/reference/application-spec.md#gcpsqlinstances). If you wish to be notified about upcoming maintenance, you can opt-in for this on the [Communications page](https://console.cloud.google.com/user-preferences/communication) in the GCP console. ### Automated backup -The database is backed up nightly at 3 AM \(GMT+1\) by default, but can be overridden in [`nais.yaml`](../../../reference/application-spec.md#gcpsqlinstancesautobackuptime) by setting `spec.gcp.sqlInstances[].autoBackupTime`. + +The database is backed up nightly at 3 AM \(GMT+1\) by default, but can be overridden in [`nais.yaml`](../../workloads/application/reference/application-spec.md#gcpsqlinstancesautobackuptime) by setting `spec.gcp.sqlInstances[].autoBackupTime`. By default, seven backups will be kept. More info [about Cloud SQL backups](https://cloud.google.com/sql/docs/postgres/backup-recovery/backups). The backups can be found in the [Google Cloud SQL instance](https://cloud.google.com/sql) dashboard. @@ -146,7 +153,7 @@ The creation of the database takes about ten minutes, and the credential setting ### Workaround for password synchronization issues -We recommend using [nais-cli](../../nais-cli/install.md) for rotating password for your Postgres database user. +We recommend using [nais-cli] for rotating password for your Postgres database user. ```bash nais postgres password rotate appname @@ -187,7 +194,7 @@ The application will connect to the database using [Cloud SQL Proxy](https://clo NAIS will add and configure the proxy client container as a sidecar in the pod, making it available on `localhost` for the application. The application will then connect to the proxy using standard database protocol just as if it was the actual database. -![The diagram shows how the application connects to the database using Cloud SQL Proxy. Cloud SQL connects to an instance, the proxy server communicates with the proxy client using a TCP secure tunnel. The proxy client is a sidecar in the pod, available on the localhost for the application on the client machine.](../../../assets/sqlproxy.svg) +![The diagram shows how the application connects to the database using Cloud SQL Proxy. Cloud SQL connects to an instance, the proxy server communicates with the proxy client using a TCP secure tunnel. The proxy client is a sidecar in the pod, available on the localhost for the application on the client machine.](../../assets/sqlproxy.svg) For more detailed information, check out the [Cloud SQL Proxy documentation](https://cloud.google.com/sql/docs/postgres/sql-proxy) @@ -212,28 +219,29 @@ With `.spec.gcp.sqlInstances[].databases[].envVarPrefix` set to `DB` and additio Databases should always be accessed using a personal account, and the access should ideally be temporary. !!! info - [Personal database access can also be configured using the nais-cli](../../nais-cli/install.md). + + [Personal database access can also be configured using the nais-cli][nais-cli] ### Prerequisites -???+ check "Step 1. Install local binaries" +!!! check "Step 1. Install local binaries" This guide assumes that you have the following installed on your local machine: - - [nais-cli](../../nais-cli/install.md) + - [nais-cli] - kubectl - (Optionally for cli access) [psql binary](https://blog.timescale.com/how-to-install-psql-on-mac-ubuntu-debian-windows/) We will use the `nais postgres` command from the CLI to set up the database access. -???+ check "Step 2. Allow your user to edit Cloud SQL resources for your project" +!!! check "Step 2. Allow your user to edit Cloud SQL resources for your project" Ensure that you have authenticated `gcloud` by running ```bash nais login ``` -???+ check "Step 3. Select the context and namespace of your application" +!!! check "Step 3. Select the context and namespace of your application" If you have installed [kubectx](https://github.com/ahmetb/kubectx) you can use the following command to select the context and namespace of your application: ```bash @@ -248,7 +256,7 @@ Databases should always be accessed using a personal account, and the access sho kubectl config set-context --current --namespace= ``` -???+ check "Step 3. One-time setup of privileges to SQL IAM users" +!!! check "Step 3. One-time setup of privileges to SQL IAM users" This is only required once per database instance. @@ -270,7 +278,7 @@ Databases should always be accessed using a personal account, and the access sho ### Granting temporary personal access -???+ check "Step 1. Create database IAM user" +!!! check "Step 1. Create database IAM user" This is required once per user and requires that you have access to the team's GCP project. @@ -280,7 +288,7 @@ Databases should always be accessed using a personal account, and the access sho This will give you a limited time access to the database unless there's already an existing permission for your user. -???+ check "Step 3. Log in with personal user" +!!! check "Step 3. Log in with personal user" Use `nais postgres proxy` to create a secure tunnel to the database. @@ -313,7 +321,7 @@ For safe upgrades, it is recommended to only do one major version at a time. ## Deleting the database -The database is not automatically removed when deleting your NAIS application. Remove unused databases to avoid incurring unnecessary costs. This is done by setting [cascadingDelete](../../../reference/application-spec.md#gcpsqlinstancescascadingdelete) in your `nais.yaml`-specification. +The database is not automatically removed when deleting your NAIS application. Remove unused databases to avoid incurring unnecessary costs. This is done by setting [cascadingDelete](../../workloads/application/reference/application-spec.md#gcpsqlinstancescascadingdelete) in your `nais.yaml`-specification. !!! danger When you delete an Cloud SQL instance, you cannot reuse the name of the deleted instance until one week from the deletion date. @@ -336,19 +344,21 @@ $ kubectl logs -c cloudsql-proxy ## Example with all configuration options -See [full example](../../../reference/application-example.md). +See [full example](../../workloads/application/reference/application-example.md). ## FAQ ### `FATAL: password authentication failed for user ""` -??? faq "Answer" +!!! faq "Answer" + The synchronization of the password to the database may have failed. See [workaround for password synchronization issues](#workaround-for-password-synchronization-issues). ### Connect to a cloned database-instance -??? faq "Answer" +!!! faq "Answer" + If you have for some reason cloned a database in the console, you need to do some manually changes on the new database to be allowed to connect to it. First you need to log in to with the old username and password, then run `GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO "cloned-user";` to give the new cloned user access to all the old tables. If you have objects outside of tables those also needs to be changed. Also remember to delete the `google-sql-appname`-secret from the cluster, so new secrets are generated for the cloned database. @@ -359,34 +369,36 @@ See [full example](../../../reference/application-example.md). #### Invalid request: backup retention should be >= transaction log retention -??? faq "Answer" +!!! faq "Answer" This error occurs when the backup retention is set to a value lower than the transaction log retention. The backup retention should be equal to or greater than the transaction log retention. You can fix this by setting the `retainedBackups` to a value equal to or greater than the transaction log retention or by setting the `transactionLogRetentionDays` to a value equal to or less than the backup retention. - This can be configured in the [NAIS manifest](../../../reference/application-spec.md#gcpsqlinstances). + This can be configured in the [NAIS manifest](../../workloads/application/reference/application-spec.md#gcpsqlinstances). Read more about [automated backups with cloud sql](https://cloud.google.com/sql/docs/mysql/backup-recovery/backups#automated-backups). #### Cannot disable cloudsql.logical_decoding while there are logical replication slots -??? faq "Answer" +!!! faq "Answer" This error occurs when you try to disable logical decoding while there are logical replication slots. [Notes and limitations](https://cloud.google.com/sql/docs/postgres/replication/configure-logical-replication#limitations-general) on disabling logical decoding. #### ...immutable field(s): [Field Name: settings.0.diskSize, Got: x, Wanted: xx]... -??? faq "Answer" +!!! faq "Answer" This error occurs when you try to change the disk size of the database instance. The disk size settings of the database instance cannot be less then current size after the instance is created. - You can fix this by specifying in the [NAIS manifest](../../../reference/application-spec.md#gcpsqlinstancesdisksize) + You can fix this by specifying in the [NAIS manifest](../../workloads/application/reference/application-spec.md#gcpsqlinstancesdisksize) the desired disk size of the database instance to be equal to or greater than the current size. - If you want to control the disk size of the instance you should disable [automatic storage increase](../../../reference/application-spec.md#gcpsqlinstancesdiskautoresize). + If you want to control the disk size of the instance you should disable [automatic storage increase](../../workloads/application/reference/application-spec.md#gcpsqlinstancesdiskautoresize). #### Not allowed to do major version upgrade from POSTGRES_x to POSTGRES_xx -??? faq "Answer" +!!! faq "Answer" This error occurs when you try to 'upgrade' the major version of the database instance to a version that is not allowed. You cant downgrade the major version of the database instance, if you want to downgrade the version you need to create a new instance with the desired version. - You can fix this by specifying in the [NAIS manifest](../../../reference/application-spec.md#gcpsqlinstancestype) - the version type to the same as the current or a higher version. \ No newline at end of file + You can fix this by specifying in the [NAIS manifest](../../workloads/application/reference/application-spec.md#gcpsqlinstancestype) + the version type to the same as the current or a higher version. + +[nais-cli]: ../../operate/cli/how-to/install.md diff --git a/docs/persistence/redis/.pages b/docs/persistence/redis/.pages new file mode 100644 index 00000000..32705eb9 --- /dev/null +++ b/docs/persistence/redis/.pages @@ -0,0 +1,5 @@ +nav: +- README.md +- 🎯 How-To: how-to +- πŸ“š Reference: reference.md +- ... diff --git a/docs/persistence/redis/README.md b/docs/persistence/redis/README.md new file mode 100644 index 00000000..c59cc66f --- /dev/null +++ b/docs/persistence/redis/README.md @@ -0,0 +1,14 @@ +--- +tags: [persistence, explanation, redis, services] +--- +# Redis + +Redis is a key value database that is used for storing and querying data. It is +a good choice for storing data that is not relational in nature and often used +for caching. + +## What's next? + +:dart: [Create Redis via Application](how-to/create-application.md) + +:dart: [Create Redis as a standalone instance](how-to/create-explicit.md). diff --git a/docs/how-to-guides/persistence/redis/README.md b/docs/persistence/redis/how-to/create-application.md similarity index 68% rename from docs/how-to-guides/persistence/redis/README.md rename to docs/persistence/redis/how-to/create-application.md index 34fa0b1e..4a322a16 100644 --- a/docs/how-to-guides/persistence/redis/README.md +++ b/docs/persistence/redis/how-to/create-application.md @@ -1,18 +1,21 @@ -# Redis +--- +tags: [how-to, redis] +--- -Nais provides Redis through Aiven via their Aiven -Operator. +# Create Redis via Application You can create many Redis instances for your `Application`. -## 0. Prerequisites -- [Member of a NAIS team](../../../explanation/team.md) +## Prerequisites +- [Member of a NAIS team](../../../explanations/team.md) -!!! warning It is not possible to share Redis instances between teams. +!!! warning -## 1. Enable Redis in your [manifest](../../../reference/application-spec.md) + It is not possible to share Redis instances between teams. -???+ note ".nais/app.yaml" +## Enable Redis in your [manifest][app-spec-redis] + +!!! note ".nais/app.yaml" ```yaml spec: redis: @@ -22,26 +25,27 @@ You can create many Redis instances for your `Application`. access: read ``` - The above snippet will allow your application to use the `sessions` Redis instance, and provide the application with credentials for a read/write user. In addition, the application will get credentials for a read-only user for the `lookup` instance. See the [manifest -reference](../../../reference/application-spec.md#redis) for other +reference][app-spec-redis] for other options for `access`. If all you need is a Redis instance for one application using just the default settings, this is all you need. If you want to share a Redis instance across applications, or want to change configuration away from the defaults, please read the [section on explicitly creating -redis instances](./create-redis-instance-explicitly.md). +Redis instances](create-explicit.md). -For each edis instance, your application will receive +For each Redis instance, your application will receive three environment variables. The environment variables use a fixed prefix, and the instance name uppercased as a suffix. -| Key | Value | | -|---------------------------------|--------------------------------------|---| -| `REDIS_URI_` | The URI for the instance | | -| `REDIS_USERNAME_` | The username to use when connecting. | | -| `REDIS_PASSWORD_` | The password to use when connecting. | | +| Key | Value | +|---------------------------------|--------------------------------------| +| `REDIS_URI_` | The URI for the instance | +| `REDIS_USERNAME_` | The username to use when connecting. | +| `REDIS_PASSWORD_` | The password to use when connecting. | + +[app-spec-redis]: ../../../workloads/application/reference/application-spec.md#redis diff --git a/docs/how-to-guides/persistence/redis/create-redis-instance-explicitly.md b/docs/persistence/redis/how-to/create-explicit.md similarity index 94% rename from docs/how-to-guides/persistence/redis/create-redis-instance-explicitly.md rename to docs/persistence/redis/how-to/create-explicit.md index 8d797374..589114e1 100644 --- a/docs/how-to-guides/persistence/redis/create-redis-instance-explicitly.md +++ b/docs/persistence/redis/how-to/create-explicit.md @@ -1,15 +1,19 @@ -# Creating a Redis instance explicitly +--- +tags: [redis, how-to] +--- + +# Create a Redis instance explicitly We recommend creating your Redis instances in their own workflow for more control over configuration, especially if you intend for multiple applications using the same Redis instance, or if you need to change configuration. Creating a Redis instance is done by adding a Redis resource to your namespace with detailed configuration. -Some configuration is enforced by the nais platform, while the rest is up to the users. +Some configuration is enforced by the NAIS platform, while the rest is up to the users. Earlier we talked about the "instance name". In reality, the actual name of the redis instance will be `redis--` (where `team name` is the same as the namespace your application resides in). The resource needs to have this full name in order to be accepted. -The default Redis created by nais looks like this: +The default Redis created by NAIS looks like this: ```yaml apiVersion: aiven.io/v1alpha1 @@ -27,7 +31,7 @@ spec: A minimal Redis resource only requires `plan` and `project`. - * `project` should match your nais tenant (`<>`) and the environment you are running in (ex. `dev`, `prod`), with a dash (`-`) in between. + * `project` should match your NAIS tenant (`<>`) and the environment you are running in (ex. `dev`, `prod`), with a dash (`-`) in between. * `plan` is the Aiven plan for your Redis instance. See Aivens list of [possible plan values](https://aiven.io/pricing?product=redis). The values are lowercased. @@ -61,7 +65,7 @@ There are some fields available that should not be used: | field | | |------------------------|-------------------------------------------------------------------------------------------------| | `authSecretRef` | Reference to a secret containing an Aiven API token. Provided via other mechanisms. | -| `connInfoSecretTarget` | Name of secret to put connection info in, not used as nais provides these via other mechanisms. | +| `connInfoSecretTarget` | Name of secret to put connection info in, not used as NAIS provides these via other mechanisms. | | `projectVPCRef` | Not used since we use `projectVpcId`. | | `serviceIntegrations` | Not used at this time. | @@ -82,7 +86,7 @@ Simple 5 steps procedure: 6. Deploy the resource using the same pipeline as you use for your Redis instance -???+ note "redis.yaml" +!!! note "redis.yaml" ```yaml --- apiVersion: aiven.io/v1alpha1 @@ -117,3 +121,4 @@ Simple 5 steps procedure: {% endif %} {% endif %} + diff --git a/docs/reference/redis.md b/docs/persistence/redis/reference.md similarity index 78% rename from docs/reference/redis.md rename to docs/persistence/redis/reference.md index ce7ca04d..bde2e59d 100644 --- a/docs/reference/redis.md +++ b/docs/persistence/redis/reference.md @@ -1,24 +1,21 @@ --- -tags: - - redis +tags: [redis, reference] --- -# Redis - -Nais provides Redis by way of Aiven via their Aiven Operator. +# Redis reference ## Configuration options The `spec.redis` field takes a list of records of two fields, instance and access. Instance is the instance name and access is the access mode. ```yaml - spec: - redis: - - instance: - access: readwrite | read | write | admin +spec: + redis: + - instance: + access: readwrite | read | write | admin ``` -every ` will give three environment variables for the applications to use, +Every `` will give three environment variables for the applications to use: | Key | Value | |------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------| diff --git a/docs/reference/README.md b/docs/reference/README.md deleted file mode 100644 index b4b7183f..00000000 --- a/docs/reference/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# References - -Reference documentation for the NAIS platform. Most useful when you need to look up details about a specific feature. \ No newline at end of file diff --git a/docs/reference/access-policy.md b/docs/reference/access-policy.md deleted file mode 100644 index 6152fa4a..00000000 --- a/docs/reference/access-policy.md +++ /dev/null @@ -1,365 +0,0 @@ -# Access Policy - -Access policies express which applications and services you are able to communicate with, both inbound and outbound. The default policy is to **deny all incoming and outgoing traffic** for your application, meaning you must be conscious of which services/application you consume, and who your consumers are. - -In NAIS, we use [Network Policies][k8s-netpol] to express access policies. Network policies are applied to the pod, and are enforced by the network itself on layer 3 and 4 (TCP/IP). This means that the network will drop any traffic that is not allowed by the policy. - - [k8s-netpol]: https://kubernetes.io/docs/concepts/services-networking/network-policies/ - -```mermaid -graph LR - accTitle: Example Access Policy - accDescr: The diagram shows three applications, A, B and C. Application A is allowed to communicate with B and C, but B and C are not allowed to communicate with A. - - A--"βœ…"-->B - - A--"βœ…"-->C - - B--"❌"-->A - - C--"❌"-->A - - subgraph accesspolicy-a[Access Policy A] - A[Application A] - end - - subgraph accesspolicy-b[Access Policy B] - B[Application B] - end - - subgraph accesspolicy-c[Access Policy C] - C[Application C] - end -``` - -## Limitations - -The access policy currently have the following limits: - -1. **No support for UDP**. This is a limitation of Kubernetes, and will be fixed in the future. -2. **Only for pod-to-pod communication**. The Access policies only apply when communicating internally within the cluster using [service discovery](./service-discovery.md), and not through [ingress traffic](./ingress.md). -3. **Only available in GCP**. Network policies are only applied in GCP clusters. However, inbound rules for authorization in the context of [_TokenX_](../security/auth/tokenx.md) or [_Azure AD_](../security/auth/azure-ad/README.md) apply to all clusters. - -## Access Policy vs. Ingress - -Access policies are only applied to pod-to-pod communication, and not to ingress traffic. This means that you can still use ingress to expose your application to the Internet, and use access policies to control which applications can communicate with your application. - -Outbound requests to ingresses are regarded as external hosts, even if these ingresses exist in the same cluster. - -## Inbound rules - -Inbound rules specifies what other applications _in the same cluster_ your application receives traffic from. - -### Receive requests from other app in the same namespace - -For app `app-a` to be able to receive incoming requests from `app-b` in the same cluster and the same namespace, this specification is needed for `app-a`: - -=== "nais.yaml" - - ```yaml - apiVersion: "nais.io/v1alpha1" - kind: "Application" - metadata: - name: app-a - ... - spec: - ... - accessPolicy: - inbound: - rules: - - application: app-b - ``` - -=== "visualization" - - ```mermaid - graph LR - accTitle: Receive requests from other app in the same namespace - accDescr: The diagram shows two applications in the same namespace, A and B. Application A is allowed to receive requests from B. - - app-b--"βœ…"-->app-a - - subgraph mynamespace - app-a - app-b - end - ``` - -### Receive requests from other app in the another namespace - -For app `app-a` to be able to receive incoming requests from `app-b` in the same cluster but another namespace \(`othernamespace`\), this specification is needed for `app-a`: - -=== "nais.yaml" - - ```yaml - apiVersion: "nais.io/v1alpha1" - kind: "Application" - metadata: - name: app-a - ... - spec: - ... - accessPolicy: - inbound: - rules: - - application: app-b - namespace: othernamespace - ``` - -=== "visualization" - - ```mermaid - graph LR - accTitle: Receive requests from other app in the another namespace - accDescr: The diagram shows two applications in different namespaces, A and B. Application A is allowed to receive requests from B. - - app-b--"βœ…"-->app-a - - subgraph mynamespace - app-a - end - - subgraph othernamespace - app-b - end - ``` - -## Outbound rules - -`spec.accessPolicy.outbound.rules` specifies which applications _in the same cluster_ you allow your application to send requests to. To open for external applications, use the field `spec.accessPolicy.outbound.external`. - -### Send requests to other app in the same namespace - -For app `app-a` to be able to send requests to `app-b` in the same cluster and the same namespace, this specification is needed for `app-a`: - -=== "nais.yaml" - - ```yaml - apiVersion: "nais.io/v1alpha1" - kind: "Application" - metadata: - name: app-a - ... - spec: - ... - accessPolicy: - outbound: - rules: - - application: app-b - ``` - -=== "visualization" - - ```mermaid - graph LR - accTitle: Send requests to other app in the same namespace - accDescr: The diagram shows two applications in the same namespace, A and B. Application A is allowed to send requests to B. - - app-a--"βœ…"-->app-b - - subgraph mynamespace - app-a - app-b - end - ``` - -### Send requests to other app in the another namespace - -For app `app-a` to be able to send requests requests to `app-b` in the same cluster but in another namespace \(`othernamespace`\), this specification is needed for `app-a`: - -=== "nais.yaml" - - ```yaml - apiVersion: "nais.io/v1alpha1" - kind: "Application" - metadata: - name: app-a - ... - spec: - ... - accessPolicy: - outbound: - rules: - - application: app-b - namespace: othernamespace - ``` - -=== "visualization" - - ```mermaid - graph LR - accTitle: Send requests to other app in the another namespace - accDescr: The diagram shows two applications in different namespaces, A and B. Application A is allowed to send requests to B. - - app-a--"βœ…"-->app-b - - subgraph mynamespace - app-a - end - - subgraph othernamespace - app-b - end - ``` - -### External services - -External services are services that are not running in the same cluster, but are reachable from the cluster. This could be services running in other clusters, or services running in the same cluster but outside the cluster network. - -Since this is not a native feature of Kubernetes Network Policies, we are leveraging Linkerd's [Service Profiles](https://linkerd.io/2/features/service-profiles/) to achieve this. - -In order to send requests to services outside of the cluster, `external.host` configuration is needed: - -=== "nais.yaml" - - ```yaml - apiVersion: "nais.io/v1alpha1" - kind: "Application" - metadata: - name: app-a - ... - spec: - ... - accessPolicy: - outbound: - external: - - host: www.external-application.com - ``` - -=== "visualization" - - ```mermaid - graph LR - accTitle: External services - accDescr: The diagram shows an application, A, that is allowed to send requests to an external service. - - app-a--"βœ…"-->www.external-application.com - - subgraph cluster - subgraph mynamespace - app-a - end - end - ``` - -Default hosts that are added and accessible for every application: - -| Host / service | Port | Protocol | -| --------------------------- | ---- | --------- | -| `kube-dns` | 53 | UDP / TCP | -| `metadata.google.internal` | 80 | TCP | -| `private.googleapis.com` | 443 | TCP | -| `login.microsoftonline.com` | 443 | TCP | -| `graph.microsoft.com` | 443 | TCP | -| `aivencloud.com` | 443 | TCP | -| `unleash.nais.io` | 443 | TCP | - -#### Global Service Entries - -There are some services that are automatically added to the mesh in [dev-gcp](https://github.com/navikt/nais-yaml/blob/master/vars/dev-gcp.yaml) and [prod-gcp](https://github.com/navikt/nais-yaml/blob/master/vars/prod-gcp.yaml) (search for `global_serviceentries`). - -## Advanced: Resources created by Naiserator - -The previous application manifest examples will create Kubernetes Network Policies. - -### Kubernetes Network Policy - -#### Default policy - -Every app created will have this default network policy that allows traffic to Linkerd and kube-dns. -It also allows incoming traffic from the Linkerd control plane and from tap and prometheus in the linkerd-viz namespace. This is what enables monitoring via the linkerd dashboard. -These policies will be created for every app, also those who don't have any access policies specified. - -```yaml -apiVersion: extensions/v1beta1 -kind: NetworkPolicy -metadata: - labels: - app: appname - team: teamname - name: appname - namespace: teamname -spec: - egress: - - to: - - namespaceSelector: - matchLabels: - linkerd.io/is-control-plane: "true" - - namespaceSelector: {} - podSelector: - matchLabels: - k8s-app: kube-dns - - ipBlock: - cidr: 0.0.0.0/0 - except: - - 10.6.0.0/15 - - 172.16.0.0/12 - - 192.168.0.0/16 - ingress: - - from: - - namespaceSelector: - matchLabels: - linkerd.io/is-control-plane: "true" - - from: - - namespaceSelector: - matchLabels: - linkerd.io/extension: viz - podSelector: - matchLabels: - component: tap - - from: - - namespaceSelector: - matchLabels: - linkerd.io/extension: viz - podSelector: - matchLabels: - component: prometheus - podSelector: - matchLabels: - app: appname - policyTypes: - - Ingress - - Egress - -``` - -#### Kubernetes network policies - -The applications specified in `spec.accessPolicy.inbound.rules` and `spec.accessPolicy.outbound.rules` will append these fields to the default Network Policy: - -```yaml -apiVersion: extensions/v1beta1 -kind: NetworkPolicy -... -spec: - egress: - - to: - ... - - namespaceSelector: - matchLabels: - kubernetes.io/metadata.name: othernamespace - podSelector: - matchLabels: - app: app-b - - podSelector: - matchLabels: - app: app-b - - from: - - namespaceSelector: - matchLabels: - kubernetes.io/metadata.name: othernamespace - podSelector: - matchLabels: - app: app-b - - podSelector: - matchLabels: - app: app-b - podSelector: - matchLabels: - app: appname - policyTypes: - - Egress - - Ingress -``` - -If you are working directly with Kubernetes Network Policies, we are recommending the Cilium Policy Editor which can be found at [editor.cilium.io](https://editor.cilium.io/). diff --git a/docs/reference/cli/.pages b/docs/reference/cli/.pages deleted file mode 100644 index 0f52a8ea..00000000 --- a/docs/reference/cli/.pages +++ /dev/null @@ -1 +0,0 @@ -title: CLI diff --git a/docs/reference/default-variables.md b/docs/reference/default-variables.md deleted file mode 100644 index 161f2ae4..00000000 --- a/docs/reference/default-variables.md +++ /dev/null @@ -1,12 +0,0 @@ -# Default variables available for Application - -These environment variables will be injected into your application container - -| variable | example | source | -| :--- | :--- | :--- | -| NAIS\_APP\_NAME | myapp | metadata.name from app.yaml | -| NAIS\_NAMESPACE | default | metadata.namespace from app.yaml | -| NAIS\_APP\_IMAGE | navikt/myapp:69 | spec.image from app.yaml | -| NAIS\_CLUSTER\_NAME | prod | which environment you are running in | -| NAIS\_CLIENT\_ID | prod-fss:default:myapp | concatenation of cluster, namespace and app name | - diff --git a/docs/reference/deploy-action-config.md b/docs/reference/deploy-action-config.md deleted file mode 100644 index c66a7ef5..00000000 --- a/docs/reference/deploy-action-config.md +++ /dev/null @@ -1,24 +0,0 @@ -# Deploy action configuration - -This document describes the available configuration options for the NAIS deploy GitHub action. - -| Environment variable | Default | Description | -|:---------------------|:-------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| APIKEY | \(required\) | NAIS deploy API key. Obtained from [console](https://console.nav.cloud.nais.io). | -| CLUSTER | \(required\) | Which NAIS cluster to deploy into. | -| DRY\_RUN | `false` | If `true`, run templating and validate input, but do not actually make any requests. | -| ENVIRONMENT | \(auto-detect\) | The environment to be shown in GitHub Deployments. Defaults to `CLUSTER:NAMESPACE` for the resource to be deployed if not specified, otherwise falls back to `CLUSTER` if multiple namespaces exist in the given resources. | -| OWNER | \(auto-detect\) | Owner of the repository making the request. | -| PRINT\_PAYLOAD | `false` | If `true`, print templated resources to standard output. | -| QUIET | `false` | If `true`, suppress all informational messages. | -| REF | `master` \(auto-detect\) | Commit reference of the deployment. Shown in GitHub's interface. | -| REPOSITORY | \(auto-detect\) | Name of the repository making the request. | -| RESOURCE | \(required\) | Comma-separated list of files containing Kubernetes resources. Must be JSON or YAML format. | -| RETRY | `true` | Automatically retry deploying if deploy service is unavailable. | -| TEAM | \(auto-detect\) | Team making the deployment. | -| TIMEOUT | `10m` | Time to wait for deployment completion, especially when using `WAIT`. | -| VAR | | Comma-separated list of template variables in the form `key=value`. Will overwrite any identical template variable in the `VARS` file. | -| VARS | `/dev/null` | File containing template variables. Will be interpolated with the `$RESOURCE` file. Must be JSON or YAML format. | -| WAIT | `true` | Block until deployment has completed with either `success`, `failure` or `error` state. | - -Note that `OWNER` and `REPOSITORY` corresponds to the two parts of a full repository identifier. If that name is `navikt/myapplication`, those two variables should be set to `navikt` and `myapplication`, respectively. diff --git a/docs/reference/environments.md b/docs/reference/environments.md deleted file mode 100644 index 0cde4053..00000000 --- a/docs/reference/environments.md +++ /dev/null @@ -1,3 +0,0 @@ -# Environments - -n/a diff --git a/docs/reference/kyverno-policies.md b/docs/reference/kyverno-policies.md deleted file mode 100644 index debaf646..00000000 --- a/docs/reference/kyverno-policies.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -tags: - - Kyverno ---- - -# Kyverno policies - -Nais enforces certain cluster policies using kyverno, in addition to different baseline security -policies you will also find some custom policies for the nais platform. - -## 001 - Add spot toleration - -This policy adds a toleration for pods to be deployed to nodes on spot -instances, for cost reasons. - -## 002 - Default allow egress - -This policy generates a default allow egress NetworkPolicy for all -Namespaces. It allows all egress traffic except for RFC 1918 private -address space. This policy is based on the following Kubernetes -NetworkPolicy: -https://kubernetes.io/docs/concepts/services-networking/network-policies/#default-allow-all-egress - -## 003 - Deny image registries - -This policy denies images from registries not on the list of allowed -registries. - -### Message - - Image not from an approved registry. Upload the image to an approved registry and try again. - -## 004 - Deny creation of Kafka Topics - -This policy Denies the creation of Kafka Topics. Documentation: -https://docs.nais.io/how-to-guides/persistence/kafka/create/ - -### Message - -Kafka Topic resource is not supported in this cluster\nDocumentation: https://docs.nais.io/how-to-guides/persistence/kafka/create/ - -## 005 - Deny deletion of Kafka topics - -This policy Denies the deletion of Kafka topics without the -kafka.nais.io/removeDataWhenResourceIsDeleted annotation. -Documentation: -https://docs.nais.io/how-to-guides/persistence/kafka/delete/ - -### Message - -Deleting Topic is not allowed without the kafka.nais.io/removeDataWhenResourceIsDeleted annotation.\nDocumentation: https://docs.nais.io/how-to-guides/persistence/kafka/delete/ - - -## 006 - Deny specific service types - -This policy denies the creation of services with types other than ClusterIP and ExternalName. -This policy is based on the example policy from the Kyverno documentation. -https://kyverno.io/docs/writing-policies/deny-service-types/ - -### Message - -Service type must be one of ClusterIP or ExternalName in this namespace. - -## 007 - Replace legacy GitHub registry - -This policy rewrites references to the old GitHub registry (docker.pkg.github.com) with the new one (ghcr.io). - -## 008 - Verify SLSA Provenance (Keyless) - -This policy uses artifact provenance to identify how an artifact was produced -and from where it originated. SLSA provenance is an industry-standard -method of representing that provenance. This policy verifies that an -image has SLSA provenance and was signed by the expected subject and issuer -when produced through GitHub Actions. It requires configuration based upon -your own values. - -## 009 - Ephemeral containers with allowed images and limited capabilities - -This policies ensures that ephemeral containers use allowed images and have limited capabilities. -When using 'kubectl debug' please set flag `--profile=restricted`. -For-example: `kubectl debug -it --image=cgr.dev/chainguard/busybox:latest --profile=restricted` - -### Message - -The fields spec.ephemeralContainers[*].image requires to be set for allowed image -see `https://docs.nais.io/basics/debug`. -Running as root is not allowed. The fields spec.ephemeralContainers[*].securityContext.runAsNonRoot -must be `true`, and spec.ephemeralContainers[*].securityContext.capabilities.drop -must be set to `- ALL` to reduce capabilities. -The use of `kubectl debug` requires to set `--profile=restricted`. - -## 010 - Aiven operator - -This policy denies invalid names and projects, and missing project vpcs. Please see the documentation at https://docs.nais.io/how-to-guides/persistence/redis#creating-a-redis-instance-explicitly or https://docs.nais.io/how-to-guides/persistence/opensearch/create depending on your usecase. - -### message - -Invalid name. Please see https://docs.nais.io/how-to-guides/persistence/redis#creating-a-redis-instance-explicitly or https://docs.nais.io/how-to-guides/persistence/opensearch/create" - - -## 011 - Validate fields for Kafka resources. - -This policy validates that the fields for the given resources has allowed values. -Currently only validates the pool field. - -### Message -Kafka pool {{ "{{ request.object.spec.pool }}" | quote }} is not supported in this cluster. -Allowed values: [{{ $valid | join ", " }}] - -Please see the documentation at https://docs.nais.io/how-to-guides/persistence/kafka/create/ - - -## 012 - Validate fields for Azure AD resources - -This policy validates that Azure AD fields for the given resource has allowed values. Currently only validates the tenant field. - -### Message - -Azure AD tenant "{{ request.object.spec.tenant }}" is not supported in this cluster. Allowed values: [nav.no] -Please see the documentation at https://doc.nais.io/security/auth/azure-ad/ diff --git a/docs/reference/secrets.md b/docs/reference/secrets.md deleted file mode 100644 index d54719a3..00000000 --- a/docs/reference/secrets.md +++ /dev/null @@ -1,45 +0,0 @@ -# Secrets - -This is the reference documentation for [secrets](../explanation/secrets.md) on the NAIS platform. - -## Console - -Visit [NAIS Console :octicons-link-external-16:](https://console.<>.cloud.nais.io) to find and manage your team's user-defined secrets. - -## How-To Guides - -- :dart: [Get started with secrets in Console](../how-to-guides/secrets/console.md) -- :dart: [Use a secret in your workload](../how-to-guides/secrets/workload.md) - -## Workloads - -Use a secret in your [workload](../explanation/workloads/README.md) by referencing them in your `nais.yaml` manifest. - -The secret can be made available as environment variables or files. - -### Environment Variables - -```yaml -spec: - envFrom: - - secret: -``` - -See also: - -- :books: [Application reference](../reference/application-spec.md#envfromsecret) -- :books: [NaisJob reference](../reference/naisjob-spec.md#envfromsecret) - -### Files - -```yaml -spec: - filesFrom: - - secret: - mountPath: /var/run/secrets/ -``` - -See also: - -- :books: [Application reference](../reference/application-spec.md#filesfromsecret) -- :books: [NaisJob reference](../reference/naisjob-spec.md#filesfromsecret) diff --git a/docs/reference/service-discovery.md b/docs/reference/service-discovery.md deleted file mode 100644 index f1ef113f..00000000 --- a/docs/reference/service-discovery.md +++ /dev/null @@ -1,80 +0,0 @@ -# Service Discovery in Kubernetes - -Applications deployed to Kubernetes are exposed through what is known as a [`Service`][k8s-service-discovery]. This is an address that allows for direct communication within a Kubernetes cluster without having to go through an external ingress, load balancer, or proxy. - -```mermaid -graph LR - accTitle: Service Discovery - accDescr: The diagram below how App A can communicate with App B directly. - app-a[App A] --http://app-b --> app-b[App B] -``` - -This is the recommended way to communicate between applications in the same Kubernetes cluster. This avoids having to expose your application to the outside world, and allows for direct communication between applications. - -A `Service` in Kubernetes has some interesting properties: - -1. It provides a single, stable address for a set of pods. This mens that if a pod dies, moves or is upgraded, the `Service` will continue to point to the remaining pods. -2. It can load balance traffic across multiple pods. This is useful for scaling out your application without having to change the address of the `Service` or update clients consuming your application. -3. Translates between ports. This is useful if you want to expose a service on a different port than the one your application is listening on. For example, you can expose port `80` on the `Service` and have it forward to port `8080` on the pod. - -Services available can be viewed with `kubectl get service` in a particular namespace. The service name for a [NAIS Application](./application-spec.md) is the same as the Application name (`metdata.name`) and is the same across any cluster where the Application is deployed. This allows for simpler configuration. - -[k8s-service-discovery]: https://kubernetes.io/docs/concepts/services-networking/service/ - -```mermaid -graph LR - accTitle: Service Discovery - accDescr: The diagram below how Pod A can communicate with Pod B through a Service. - - pod-a --port 80--> service-b - service-b --port 8080--> pod-b-1 - service-b --port 8080--> pod-b-2 - - pod-a[Pod A] - - subgraph "Application B" - pod-b-1[Pod B] - pod-b-2[Pod B] - service-b[Service B] - end -``` - -## Google Cloud Platform - -!!! warning - Ensure that you've set up proper [access policies](./access-policy.md) for your applications. - -The full hostname of a service on GCP follows this format: - -```text -http://..svc.cluster.local -``` - -## On-prem - -The full hostname of a service on-prem follows this format: - -```text -http://..svc.nais.local -``` - -## Short names - -You often won't need to use the full hostname to contact another service. - -If you’re addressing a service in the same namespace, you can use just the service name to contact it: - -```text -http:// -``` - -If the service exists in a different namespace, you must add the appropriate namespace: - -```text -http://. -``` - -!!! info "Note for on-prem" - If your application has [webproxy](./application-spec.md#webproxy) enabled, you should use the full hostname for all service discovery calls. - - This is to ensure that your application does not attempt to perform these in-cluster calls through the proxy, as the environment variable `NO_PROXY` includes `*.local`. diff --git a/docs/security/.pages b/docs/security/.pages index 796ba72a..452dd2f6 100644 --- a/docs/security/.pages +++ b/docs/security/.pages @@ -1,6 +1 @@ title: Security -nav: - - antivirus.md - - auth - - salsa - - ... diff --git a/docs/security/README.md b/docs/security/README.md index da9b50e1..5adbf114 100644 --- a/docs/security/README.md +++ b/docs/security/README.md @@ -1,4 +1,5 @@ --- +tags: [explanation] description: >- NAIS is a platform for building, deploying and operating applications in a secure manner. This document describes on a high level how NAIS achieves this and what is expected of those who use NAIS. @@ -41,7 +42,7 @@ policies. ## Team Isolation -Each team in NAIS has its own isolated environment, which is only accessible by +Each [team](../explanations/team.md) in NAIS has its own isolated environment, which is only accessible by the members of the team. This is achieved by creating a separate Kubernetes namespace and Google Cloud project that is only accessible by the members of the team. @@ -83,8 +84,6 @@ team-b-app --> team-b-db team-c-app --> team-c-db ``` -Teams are managed in [NAIS Teams](../explanation/team.md). - ## Secure Software Development Lifecycle (Secure SDLC) NAIS is not a complete solution for secure software development lifecycle. It is @@ -115,7 +114,7 @@ provided by NAIS: NAIS provides a secure way to store [secrets] for use by applications. These secrets are encrypted at rest and are only accessible by applications and members of a given team. -[secrets]: ../explanation/secrets.md +[secrets]: ../services/secrets/README.md #### External dependencies @@ -138,7 +137,7 @@ Software Artifacts (SLSA)][slsa]. This means that every application is deployed using a secure supply chain that ensures that the application is deployed in a secure manner. -[slsa]: salsa/README.md +[slsa]: ../services/salsa.md #### Security Policies @@ -175,14 +174,14 @@ The following security policies are enforced by NAIS: Developer access control in NAIS is backed by [Google Cloud IAM][google-iam] and [Kubernetes RBAC][kubernetes-rbac]. The platform is responsible for setting up the necessary roles and permissions in Google Cloud IAM and Kubernetes RBAC -according to the teams registered in [NAIS Teams](../explanation/team.md) by the +according to the teams registered in [NAIS Teams](../explanations/team.md) by the developers. Tools and services provided by the platform to the developers are exposed securely in two ways: 1. On a private network only accessible to authenticated users over -[naisdevice](../explanation/naisdevice.md) to trusted devices using secure +[naisdevice](../operate/naisdevice/README.md) to trusted devices using secure [WireGuard][wireguard] VPN tunnels. 1. On a public network behind [Identity Aware Proxy (IAP)][google-iap] which @@ -196,7 +195,7 @@ ensures that all developers are authenticated with their personal user accounts. #### User authentication User authentication and authorization ("authnz") is the responsibility of each -application running on the plattform. Authorization (i.e. "who is allowed to see +application running on the platform. Authorization (i.e. "who is allowed to see and do what under which circumstances") is part of the business logic for each domain, so it makes sense that it is handled by the teams in their apps. Doing authnz right is complicated, so the plattform offers a few tools and services to @@ -223,7 +222,7 @@ for the other OIDC/OAuth uses cases mentioned above. #### Network security Network security in NAIS is achieved by [Access -Policy](../how-to-guides/access-policies.md) that is backed by [Kubernetes +Policy](../workloads/how-to/access-policies.md) that is backed by [Kubernetes Network Policies][kubernetes-network-policies]. This controls traffic between pods in the same cluster as well as outgoing traffic from the cluster. @@ -243,11 +242,11 @@ Distributed Denial of Service (DDoS) protection. #### Logging and monitoring Application logs are collected and stored in -[Kibana](../explanation/observability/logging.md) together with infrastructure +[Kibana](../observability/logging/README.md) together with infrastructure components running in the cluster. Application metrics are collected and stored in -[Prometheus](../explanation/observability/metrics.md) together with infrastructure +[Prometheus](../observability/metrics/README.md) together with infrastructure components running in the cluster. Infrastructure, network flow logs and IAM audit logs are available from diff --git a/docs/security/auth/.pages b/docs/security/auth/.pages index 9cf04470..98c93c2a 100644 --- a/docs/security/auth/.pages +++ b/docs/security/auth/.pages @@ -1,9 +1,11 @@ title: Auth nav: - - concepts.md - - development.md - - azure-ad - - idporten.md - - tokenx.md - - maskinporten - - ... +- README.md +- concepts.md +- development.md +- azure-ad +- idporten.md +- tokenx.md +- maskinporten +- wonderwall.md +- ... diff --git a/docs/security/auth/README.md b/docs/security/auth/README.md index f3f0ac86..f51c3cc3 100644 --- a/docs/security/auth/README.md +++ b/docs/security/auth/README.md @@ -1,4 +1,5 @@ --- +tags: [authentication, explanation] description: Services and addons to support authentication (AuthN) & authorization (AuthZ) --- diff --git a/docs/security/auth/azure-ad/.pages b/docs/security/auth/azure-ad/.pages index 5aae50a6..184e21eb 100644 --- a/docs/security/auth/azure-ad/.pages +++ b/docs/security/auth/azure-ad/.pages @@ -1,7 +1,8 @@ title: Azure AD nav: - - configuration.md - - usage.md - - sidecar.md - - faq-troubleshooting.md - - ... +- README.md +- configuration.md +- usage.md +- sidecar.md +- faq-troubleshooting.md +- ... diff --git a/docs/security/auth/azure-ad/README.md b/docs/security/auth/azure-ad/README.md index 997638a2..6e1c4a96 100644 --- a/docs/security/auth/azure-ad/README.md +++ b/docs/security/auth/azure-ad/README.md @@ -1,5 +1,6 @@ --- title: Azure AD +tags: [authentication, azure-ad, services] description: Enabling authentication and authorization in internal web applications. --- diff --git a/docs/security/auth/azure-ad/configuration.md b/docs/security/auth/azure-ad/configuration.md index b26f25db..e599fb46 100644 --- a/docs/security/auth/azure-ad/configuration.md +++ b/docs/security/auth/azure-ad/configuration.md @@ -1,10 +1,13 @@ +--- +tags: [azure-ad] +--- # Configuration ## Spec Minimal example below. -See the complete specification in the [NAIS manifest](../../../reference/application-spec.md#azure). +See the complete specification in the [NAIS manifest](../../../workloads/application/reference/application-spec.md#azure). === "nais.yaml" ```yaml @@ -31,7 +34,7 @@ Azure AD is an external service. The platform automatically configures outbound You do _not_ have to explicitly configure outbound access to Azure AD yourselves in GCP. -If you're on-premises however, you must enable and use [`webproxy`](../../../reference/application-spec.md#webproxy). +If you're on-premises however, you must enable and use [`webproxy`](../../../workloads/application/reference/application-spec.md#webproxy). ## Access Policy diff --git a/docs/security/auth/azure-ad/faq-troubleshooting.md b/docs/security/auth/azure-ad/faq-troubleshooting.md index f8ec2531..f63899bc 100644 --- a/docs/security/auth/azure-ad/faq-troubleshooting.md +++ b/docs/security/auth/azure-ad/faq-troubleshooting.md @@ -1,3 +1,6 @@ +--- +tags: [azure-ad] +--- # FAQ / Troubleshooting This page lists common problems and solutions when authenticating with Azure AD. diff --git a/docs/security/auth/azure-ad/sidecar.md b/docs/security/auth/azure-ad/sidecar.md index 88930d34..3dc6cd3c 100644 --- a/docs/security/auth/azure-ad/sidecar.md +++ b/docs/security/auth/azure-ad/sidecar.md @@ -1,5 +1,6 @@ --- title: Sidecar +tags: [azure-ad, sidecar] description: Reverse-proxy that handles automatic authentication and login/logout flows for Azure AD. --- @@ -9,7 +10,7 @@ The Azure AD sidecar is a reverse proxy that provides functionality to perform A !!! warning "Availability" - The sidecar is only available in the [Google Cloud Platform](../../../reference/environments.md#google-cloud-platform-gcp) clusters. +The sidecar is only available in the [Google Cloud Platform](../../../workloads/reference/environments.md#google-cloud-platform-gcp) clusters. ## Spec @@ -30,7 +31,7 @@ Minimal example below. enabled: true ``` -See the [NAIS manifest reference](../../../reference/application-spec.md#azuresidecar) for the complete specification. +See the [NAIS manifest reference](../../../workloads/application/reference/application-spec.md#azuresidecar) for the complete specification. The above example will provision a unique Azure AD application and enable a sidecar that uses said application. @@ -41,7 +42,7 @@ For configuration of the Azure AD application itself, see [the Configuration pag !!! info "Prerequisites" - If you're unfamiliar with Azure AD, review the [core concepts](README.md#concepts). - - Ensure that you define at least one [ingress](../../../reference/application-spec.md#ingresses) for your application. + - Ensure that you define at least one [ingress](../../../workloads/application/reference/application-spec.md#ingresses) for your application. - Ensure that you configure [user access](configuration.md#users) for your application. **Users are not granted access by default**. Try out a basic user flow: diff --git a/docs/security/auth/azure-ad/usage.md b/docs/security/auth/azure-ad/usage.md index be289697..9015842b 100644 --- a/docs/security/auth/azure-ad/usage.md +++ b/docs/security/auth/azure-ad/usage.md @@ -1,3 +1,6 @@ +--- +tags: [azure-ad] +--- # Usage ## Use Cases diff --git a/docs/security/auth/concepts.md b/docs/security/auth/concepts.md index 8210d375..faff6aee 100644 --- a/docs/security/auth/concepts.md +++ b/docs/security/auth/concepts.md @@ -1,3 +1,7 @@ +--- +tags: [authentication, explanation] +--- + # Concepts This page describes basic concepts and glossary commonly referred to when working with authentication and authorization. diff --git a/docs/security/auth/development.md b/docs/security/auth/development.md index c8bc10ee..8427e419 100644 --- a/docs/security/auth/development.md +++ b/docs/security/auth/development.md @@ -1,3 +1,7 @@ +--- +tags: [authentication, explanation] +--- + # Development ## Mocking diff --git a/docs/security/auth/idporten.md b/docs/security/auth/idporten.md index f2951d2d..64ef88bf 100644 --- a/docs/security/auth/idporten.md +++ b/docs/security/auth/idporten.md @@ -1,4 +1,5 @@ --- +tags: [authentication, sidecar, services] description: Reverse-proxy that handles automatic authentication and login/logout flow public-facing authentication using ID-porten. --- @@ -9,7 +10,7 @@ description: Reverse-proxy that handles automatic authentication and login/logou NAIS provides a _sidecar_ that integrates with ID-porten, so that you can easily and securely log in and authenticate citizen end-users. !!! warning "Availability" - The sidecar is only available in the [Google Cloud Platform](../../reference/environments.md#google-cloud-platform-gcp) clusters. + The sidecar is only available in the [Google Cloud Platform](../../workloads/reference/environments.md#google-cloud-platform-gcp) clusters. ## Spec @@ -31,9 +32,9 @@ Minimal example: locale: nb # optional, default value shown ``` -See the [NAIS manifest reference](../../reference/application-spec.md#idportensidecar) for the complete specification. +See the [NAIS manifest reference](../../workloads/application/reference/application-spec.md#idportensidecar) for the complete specification. -Ensure that you also define at least one [ingress](../../reference/application-spec.md#ingresses) for your application. +Ensure that you also define at least one [ingress](../../workloads/application/reference/application-spec.md#ingresses) for your application. ## Network Connectivity diff --git a/docs/security/auth/maskinporten/README.md b/docs/security/auth/maskinporten/README.md index 685c2d5d..16eafd3f 100644 --- a/docs/security/auth/maskinporten/README.md +++ b/docs/security/auth/maskinporten/README.md @@ -1,4 +1,5 @@ --- +tags: [authentication, maskinporten, services] description: > Enabling service-to-service authentication with external agencies using Maskinporten. --- diff --git a/docs/security/auth/maskinporten/client.md b/docs/security/auth/maskinporten/client.md index 418beeff..d7561b02 100644 --- a/docs/security/auth/maskinporten/client.md +++ b/docs/security/auth/maskinporten/client.md @@ -1,3 +1,7 @@ +--- +tags: [maskinporten] +--- + # Maskinporten Client The NAIS platform provides support for declarative provisioning of Maskinporten clients. @@ -20,7 +24,7 @@ spec: webproxy: true ``` -See the [NAIS manifest reference](../../../reference/application-spec.md#maskinporten) for the complete specification. +See the [NAIS manifest reference](../../../workloads/application/reference/application-spec.md#maskinporten) for the complete specification. ## Network Connectivity @@ -29,7 +33,7 @@ The platform automatically configures outbound access to the Maskinporten hosts. You do _not_ have to explicitly configure outbound access to Maskinporten yourselves in GCP. -If you're on-premises however, you must enable and use [`webproxy`](../../../reference/application-spec.md#webproxy). +If you're on-premises however, you must enable and use [`webproxy`](../../../workloads/application/reference/application-spec.md#webproxy). ## Runtime Variables & Credentials diff --git a/docs/security/auth/maskinporten/scopes.md b/docs/security/auth/maskinporten/scopes.md index 94ff31b1..d26d9b69 100644 --- a/docs/security/auth/maskinporten/scopes.md +++ b/docs/security/auth/maskinporten/scopes.md @@ -1,3 +1,7 @@ +--- +tags: [maskinporten] +--- + # Maskinporten Scopes A _scope_ represents a permission that a given consumer has access to. @@ -25,7 +29,7 @@ spec: - orgno: "123456789" ``` -See the [NAIS manifest](../../../reference/application-spec.md#maskinporten) for the complete specification. +See the [NAIS manifest](../../../workloads/application/reference/application-spec.md#maskinporten) for the complete specification. ## Network Connectivity diff --git a/docs/security/auth/tokenx.md b/docs/security/auth/tokenx.md index 459f8d5d..8fea03cf 100644 --- a/docs/security/auth/tokenx.md +++ b/docs/security/auth/tokenx.md @@ -1,4 +1,5 @@ --- +tags: [authentication, services] description: Enabling zero trust on the application layer --- @@ -17,7 +18,7 @@ There are primarily two distinct cases where one must use TokenX: ### Spec -See the [NAIS manifest](../../reference/application-spec.md#tokenxenabled). +See the [NAIS manifest](../../workloads/application/reference/application-spec.md#tokenxenabled). ### Getting Started diff --git a/docs/security/auth/wonderwall.md b/docs/security/auth/wonderwall.md index d6cf8885..745f69f4 100644 --- a/docs/security/auth/wonderwall.md +++ b/docs/security/auth/wonderwall.md @@ -1,5 +1,6 @@ --- title: Wonderwall +tags: [authentication, sidecar, services] description: Sidecar for authentication --- @@ -14,7 +15,7 @@ As such, this is OIDC as a sidecar, or OaaS, or to explain the joke: > _Oasis - Wonderwall_ !!! warning "Availability" - Wonderwall is only available in the [Google Cloud Platform](../../reference/environments.md#google-cloud-platform-gcp) environments. + Wonderwall is only available in the [Google Cloud Platform](../../workloads/reference/environments.md#google-cloud-platform-gcp) environments. ## Overview @@ -89,7 +90,7 @@ application's ingress. ## Endpoints -The sidecar provides these endpoints under your application's [ingress](../../reference/ingress.md): +The sidecar provides these endpoints under your application's [ingress](../../workloads/reference/ingress.md): | Path | Description | Details | |--------------------------------|----------------------------------------------------------------------------|----------------------------------------------| @@ -134,7 +135,7 @@ Minimal configuration examples below: enabled: true ``` - [:octicons-arrow-right-24: See the NAIS manifest reference for the complete specification](../../reference/application-spec.md#idportensidecar). +[:octicons-arrow-right-24: See the NAIS manifest reference for the complete specification](../../workloads/application/reference/application-spec.md#idportensidecar). === "Azure AD" @@ -147,7 +148,7 @@ Minimal configuration examples below: enabled: true ``` - [:octicons-arrow-right-24: See the NAIS manifest reference for the complete specification](../../reference/application-spec.md#azuresidecar). +[:octicons-arrow-right-24: See the NAIS manifest reference for the complete specification](../../workloads/application/reference/application-spec.md#azuresidecar). ## Usage @@ -251,9 +252,9 @@ Ensure that your frontend handles the `HTTP 401` response and redirects the user Autologin will by default match all paths for your application's ingresses, except the following: - `/oauth2/*` -- [`spec.prometheus.path`](../../reference/application-spec.md#prometheuspath), if defined -- [`spec.liveness.path`](../../reference/application-spec.md#livenesspath), if defined -- [`spec.readiness.path`](../../reference/application-spec.md#readinesspath), if defined +- [`spec.prometheus.path`](../../workloads/application/reference/application-spec.md#prometheuspath), if defined +- [`spec.liveness.path`](../../workloads/application/reference/application-spec.md#livenesspath), if defined +- [`spec.readiness.path`](../../workloads/application/reference/application-spec.md#readinesspath), if defined You can define additional paths or patterns to be excluded: diff --git a/docs/services/.pages b/docs/services/.pages new file mode 100644 index 00000000..ca34aa68 --- /dev/null +++ b/docs/services/.pages @@ -0,0 +1,6 @@ +nav: +- README.md +- CDN: cdn +- secrets +- feature-toggling.md +- ... diff --git a/docs/services/README.md b/docs/services/README.md new file mode 100644 index 00000000..107ad534 --- /dev/null +++ b/docs/services/README.md @@ -0,0 +1,12 @@ +# Other services + +This section covers the rest of the NAIS functionality that didn't fit into any other categories. + +It includes services such as: + +- [CDN](cdn/README.md) +- [Secrets](secrets/README.md) +- [Feature toggling](./feature-toggling.md) +- [Anti-virus](antivirus.md) +- [Salsa](salsa.md) +- [Leader election](leader-election/README.md) diff --git a/docs/security/antivirus.md b/docs/services/antivirus.md similarity index 96% rename from docs/security/antivirus.md rename to docs/services/antivirus.md index 050cd865..339f50a3 100644 --- a/docs/security/antivirus.md +++ b/docs/services/antivirus.md @@ -1,5 +1,6 @@ --- description: Antivirus scanning of files and urls using ClamAV. +tags: [explanation, services] --- # Anti-Virus Scanning @@ -29,7 +30,7 @@ See [ClamAV documentation][clamav-docs] and [ClamAV REST API][clamav-api] for mo ## Access Policy -When using ClamAV on GCP, remember to add an [outbound access policy](../how-to-guides/access-policies.md): +When using ClamAV on GCP, remember to add an [outbound access policy](../workloads/how-to/access-policies.md): ```yaml apiVersion: "nais.io/v1alpha1" diff --git a/docs/services/cdn/.pages b/docs/services/cdn/.pages new file mode 100644 index 00000000..32705eb9 --- /dev/null +++ b/docs/services/cdn/.pages @@ -0,0 +1,5 @@ +nav: +- README.md +- 🎯 How-To: how-to +- πŸ“š Reference: reference.md +- ... diff --git a/docs/explanation/cdn.md b/docs/services/cdn/README.md similarity index 94% rename from docs/explanation/cdn.md rename to docs/services/cdn/README.md index cf6273c0..42c8b763 100644 --- a/docs/explanation/cdn.md +++ b/docs/services/cdn/README.md @@ -1,7 +1,5 @@ --- -tags: -- cdn -- explanation +tags: [cdn, explanation, services] --- # Content Delivery Network (CDN) @@ -79,5 +77,6 @@ Among many others: ## What's next? -- :dart: Learn how to [upload assets to the CDN](../how-to-guides/cdn.md) -- :books: [CDN Reference documentation](../reference/cdn.md) +:dart: Learn how to [upload assets to the CDN](how-to/upload-assets.md) + +:books: [CDN Reference documentation](reference.md) diff --git a/docs/how-to-guides/cdn.md b/docs/services/cdn/how-to/upload-assets.md similarity index 84% rename from docs/how-to-guides/cdn.md rename to docs/services/cdn/how-to/upload-assets.md index da3b071d..6d9c3687 100644 --- a/docs/how-to-guides/cdn.md +++ b/docs/services/cdn/how-to/upload-assets.md @@ -1,26 +1,24 @@ --- -tags: -- cdn -- guide +tags: [cdn, how-to] --- # Upload assets to the CDN -This how-to guide shows you how to upload assets to the [CDN](../explanation/cdn.md). +This how-to guide shows you how to upload assets to the [CDN](../README.md). -## 0. Prerequisites +## Prerequisites -- A [NAIS team](team.md). +- A [NAIS team](../../../explanations/team.md). - A GitHub repository that the team has access to. -- The repository needs to have a [GitHub workflow](github-action.md#2-create-a-github-workflow) that builds the assets you want to upload. +- The repository needs to have a [GitHub workflow](../../../build/README.md) that builds the assets you want to upload. -## 1. Authorize repository for upload +## Authorize repository for upload 1. Open [NAIS console](https://console.<>.cloud.nais.io) in your browser and select your team. 2. Select the `Repositories` tab 3. Find the repository you want to deploy from, and click `Authorize` -## 2. Upload assets with the CDN action +## Upload assets with the CDN action {% if tenant() == "nav" %} ???+ note "SPA deploy" @@ -68,9 +66,9 @@ jobs: shell: bash ``` -For more information on the inputs and outputs of the action, see the [CDN Reference](../reference/cdn.md). +For more information on the inputs and outputs of the action, see the [CDN Reference](../reference.md). -## 3. Use the uploaded assets +## Use the uploaded assets The assets from the CDN will be available at diff --git a/docs/reference/cdn.md b/docs/services/cdn/reference.md similarity index 90% rename from docs/reference/cdn.md rename to docs/services/cdn/reference.md index 7fd66022..ef6fd108 100644 --- a/docs/reference/cdn.md +++ b/docs/services/cdn/reference.md @@ -1,16 +1,15 @@ --- -tags: -- cdn -- reference +title: Content Delivery Network Reference +tags: [cdn, reference] --- # Content Delivery Network Reference -This is the reference documentation for the [CDN](../explanation/cdn.md) service. +This is the reference documentation for the [CDN](README.md) service. ## How-to guides -- :dart: [Upload assets to the CDN](../how-to-guides/cdn.md) +:dart: [Upload assets to the CDN](how-to/upload-assets.md) ## CDN Deploy Action diff --git a/docs/explanation/feature-toggling.md b/docs/services/feature-toggling.md similarity index 99% rename from docs/explanation/feature-toggling.md rename to docs/services/feature-toggling.md index 66767a6d..6c371a90 100644 --- a/docs/explanation/feature-toggling.md +++ b/docs/services/feature-toggling.md @@ -1,3 +1,7 @@ +--- +tags: [explanation, services] +--- + # Feature Toggling ## What is feature toggling? diff --git a/docs/services/leader-election/.pages b/docs/services/leader-election/.pages new file mode 100644 index 00000000..b43a840a --- /dev/null +++ b/docs/services/leader-election/.pages @@ -0,0 +1,4 @@ +nav: +- README.md +- 🎯 How-To: how-to +- ... diff --git a/docs/explanation/leader-election.md b/docs/services/leader-election/README.md similarity index 89% rename from docs/explanation/leader-election.md rename to docs/services/leader-election/README.md index 1d40dbc3..b45fb95a 100644 --- a/docs/explanation/leader-election.md +++ b/docs/services/leader-election/README.md @@ -1,3 +1,7 @@ +--- +tags: [leader-election, sidecar, explanation, services] +--- + # Leader Election With leader election it is possible to have one responsible pod. @@ -7,7 +11,7 @@ This is done by asking the [elector container](https://github.com/nais/elector) The leader election configuration does not control which pod the external service requests will be routed to. ## Elector sidecar -When you [enable leader election](../how-to-guides/leader-election.md), NAIS will inject an elector container as a sidecar into your pod. +When you [enable leader election](how-to/enable.md), NAIS will inject an elector container as a sidecar into your pod. When you have the `elector` container running in your pod, you can make a HTTP GET to the URL set in environment variable `$ELECTOR_PATH` to see which pod is the leader. diff --git a/docs/how-to-guides/leader-election.md b/docs/services/leader-election/how-to/enable.md similarity index 82% rename from docs/how-to-guides/leader-election.md rename to docs/services/leader-election/how-to/enable.md index 25648bbe..53054885 100644 --- a/docs/how-to-guides/leader-election.md +++ b/docs/services/leader-election/how-to/enable.md @@ -1,8 +1,12 @@ +--- +tags: [leader-election, how-to] +--- + # Enable Leader Election This guide will show you how to enable leader election for your application. -## 0. Enable leader election in [manifest](../reference/application-spec.md#leaderelection) +## Enable leader election in [manifest](../../../workloads/application/reference/application-spec.md#leaderelection) ???+ note ".nais/app.yaml" @@ -11,7 +15,7 @@ This guide will show you how to enable leader election for your application. leaderElection: true ``` -## 1. Using leader election in your application +## Using leader election in your application === "java" diff --git a/docs/security/salsa/README.md b/docs/services/salsa.md similarity index 98% rename from docs/security/salsa/README.md rename to docs/services/salsa.md index fb6b99df..8852fdc9 100644 --- a/docs/security/salsa/README.md +++ b/docs/services/salsa.md @@ -1,5 +1,6 @@ --- description: Github action that helps to secure supply chain for software artifacts. +tags: [explanation, services] --- # Salsa @@ -79,7 +80,7 @@ You can conduct searches within projects using the following tags: Below is a screenshot of a project utilizing the dependency graph within Dependency-Track: -![Dependency Graph](../../assets/salsa-graph.png) +![Dependency Graph](../assets/salsa-graph.png) [Dependency-Track](https://dependencytrack.org/) has a ton of features so check out the [documentation](https://docs.dependencytrack.org/) for more information. diff --git a/docs/services/secrets/.pages b/docs/services/secrets/.pages new file mode 100644 index 00000000..32705eb9 --- /dev/null +++ b/docs/services/secrets/.pages @@ -0,0 +1,5 @@ +nav: +- README.md +- 🎯 How-To: how-to +- πŸ“š Reference: reference.md +- ... diff --git a/docs/explanation/secrets.md b/docs/services/secrets/README.md similarity index 75% rename from docs/explanation/secrets.md rename to docs/services/secrets/README.md index 0bc29faa..8019e5a8 100644 --- a/docs/explanation/secrets.md +++ b/docs/services/secrets/README.md @@ -1,6 +1,10 @@ +--- +tags: [secrets, explanation, services] +--- + # Secrets -A secret is a piece of sensitive information that is used in a [workload](workloads/README.md). +A secret is a piece of sensitive information that is used in a [workload](../../workloads/README.md). This can be a password, an API key, or any other information that should not be exposed to the public. Secrets are kept separate from the codebase and configuration files that are usually stored in version control. @@ -21,7 +25,7 @@ There are two types of secrets on the NAIS platform: - :technologist: **User-defined secrets** --- - _User-defined secrets_ are managed by you and your [team](team.md). + _User-defined secrets_ are managed by you and your [team](../../explanations/team.md). - These are typically used for integrating with third-party services or APIs that are not provided by NAIS, such as Slack or GitHub. - User-defined secrets can also be used to store sensitive information specific to your application, such as encryption keys or other private configuration. @@ -29,6 +33,6 @@ There are two types of secrets on the NAIS platform: ## What's next? -- :dart: Learn how to [create and manage a secret in Console](../how-to-guides/secrets/console.md) -- :dart: Learn how to [use a secret in your workload](../how-to-guides/secrets/workload.md) -- :books: See the [reference for secrets](../reference/secrets.md) for more technical details +:dart: Learn how to [create and manage a secret in Console](how-to/console.md) + +:dart: Learn how to [use a secret in your workload](how-to/workload.md) diff --git a/docs/how-to-guides/secrets/console.md b/docs/services/secrets/how-to/console.md similarity index 88% rename from docs/how-to-guides/secrets/console.md rename to docs/services/secrets/how-to/console.md index e0eab582..cee3aea9 100644 --- a/docs/how-to-guides/secrets/console.md +++ b/docs/services/secrets/how-to/console.md @@ -1,10 +1,14 @@ +--- +tags: [secrets, how-to, console] +--- + # Get started with secrets in Console -This how-to guide shows you how to create and manage a [secret](../../explanation/secrets.md) in the NAIS Console. +This how-to guide shows you how to create and manage a [secret](../README.md) in the NAIS Console. ## Prerequisites -- You're part of a [NAIS team](../team.md) +- You're part of a [NAIS team](../../../explanations/team.md) ## List secrets diff --git a/docs/how-to-guides/secrets/workload.md b/docs/services/secrets/how-to/workload.md similarity index 88% rename from docs/how-to-guides/secrets/workload.md rename to docs/services/secrets/how-to/workload.md index 474a4206..4c858619 100644 --- a/docs/how-to-guides/secrets/workload.md +++ b/docs/services/secrets/how-to/workload.md @@ -1,18 +1,22 @@ +--- +tags: [workloads, how-to, secrets] +--- + # Use a secret in your workload -This how-to guide shows you how to reference and use a [secret](../../explanation/secrets.md) -in your [workload](../../explanation/workloads/README.md). +This how-to guide shows you how to reference and use a [secret](../README.md) +in your [workload](../../../workloads/README.md). A secret can be made available as environment variables or files, or both. ## Prerequisites -- You're part of a [NAIS team](../team.md) +- You're part of a [NAIS team](../../../explanations/team.md) - You have previously [created a secret](console.md#create-a-secret) for your team - A Github repository where the NAIS team has access - The repository contains a valid workload manifest (`nais.yaml`) -## Expose secret as environment variables +## Expose secret as environment variables 1. Add a reference to the secret in the workload's `nais.yaml` manifest. diff --git a/docs/services/secrets/reference.md b/docs/services/secrets/reference.md new file mode 100644 index 00000000..9c721f30 --- /dev/null +++ b/docs/services/secrets/reference.md @@ -0,0 +1,56 @@ +--- +title: Secrets Reference +tags: [secrets, reference] +--- + +# Secrets Reference + +This is the reference documentation for [secrets](README.md) on the NAIS platform. + +## Console + +Visit [NAIS Console :octicons-link-external-16:](https://console.<>.cloud.nais.io) to find and manage your team's user-defined secrets. + +## How-To Guides + +:dart: [Get started with secrets in Console](how-to/console.md) + +:dart: [Use a secret in your workload](how-to/workload.md) + +## Workloads + +Use a secret in your [workload](../../workloads/README.md) by referencing them in your `nais.yaml` manifest. + +The secret can be made available as environment variables or files. + +### Environment Variables + +```yaml +spec: + envFrom: + - secret: +``` + +See also: + +:books: [Application reference][application] + +:books: [NaisJob reference][naisjob] + +### Files + +```yaml +spec: + filesFrom: + - secret: + mountPath: /var/run/secrets/ +``` + +See also: + +:books: [Application reference][application] + +:books: [NaisJob reference][naisjob] + +[application]: ../../workloads/application/reference/application-spec.md#envfromsecret +[naisjob]: ../../workloads/job/reference/naisjob-spec.md#envfromsecret diff --git a/docs/reference/tags.md b/docs/tags.md similarity index 100% rename from docs/reference/tags.md rename to docs/tags.md diff --git a/docs/tutorial/.pages b/docs/tutorial/.pages deleted file mode 100644 index bddf5747..00000000 --- a/docs/tutorial/.pages +++ /dev/null @@ -1 +0,0 @@ -title: Tutorials diff --git a/docs/tutorial/README.md b/docs/tutorial/README.md deleted file mode 100644 index f8325f5c..00000000 --- a/docs/tutorial/README.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -α΄΄β‚’α΄΄β‚’α΄΄β‚’: false -hide: - - feedback - - footer ---- - -# NAIS Documentation -Learning-oriented lessons that take you through a series of steps to complete a project. Most useful when you want to get started with NAIS. - -
-- :octicons-rocket-24:{ .lg .middle } **1. Hello NAIS** - - --- - - This tutorial will take you through the process of getting a simple web application up and running on NAIS. No previous experience with NAIS is required. - - [:octicons-arrow-right-24: Hello NAIS](./hello-nais/hello-nais-1.md) - -
diff --git a/docs/tutorial/hello-nais/hello-nais-1.md b/docs/tutorial/hello-nais/hello-nais-1.md deleted file mode 100644 index e7ff142a..00000000 --- a/docs/tutorial/hello-nais/hello-nais-1.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -tags: [tutorial] ---- -# Part 1 - Create application - -This tutorial will take you through the process of getting a simple application up and running on NAIS. - -## Prerequisites - -- You have a GitHub account connected to your GitHub organization (e.g. `navikt`) -- [naisdevice installed](../../how-to-guides/naisdevice/install.md) -- [Member of a NAIS team](../../explanation/team.md) -- [GitHub CLI installed](https://cli.github.com/) - -???+ note "Conventions" - - Throughout this guide, we will use the following conventions: - - - `` - The name of your NAIS application (e.g. `joannas-first`) - - `` - The name of your NAIS team (e.g. `onboarding`) - - `` - Your GitHub organization (e.g. `navikt`) - - `` - The name of the environment you want to deploy to (e.g. `dev`) - - **NB!** Choose names with *lowercase* letters, numbers and dashes only. - -## 1. Create your own GitHub repository - -Create your own repo using the [nais/hello-nais](https://github.com/nais/hello-nais/) as a template. - -You create a new repository through either the [GitHub UI](https://github.com/new?template_name=hello-nais&template_owner=nais) or through the GitHub CLI: - -```bash -gh repo create / --template nais/hello-nais --private --clone -``` - -```bash -cd -``` - -## 2. Grant your team access to your repository - -Open your repository: - -```bash -gh repo view --web -``` - -Click on `Settings` -> `Collaborators and teams` -> `Add teams`. - -Select your team, and grant them the `Write` role. - -You have now successfully created your own application repository and granted your team access to it. -In the next steps we will have a closer look at the files needed to make this application NAIS! diff --git a/docs/tutorial/hello-nais/hello-nais-2.md b/docs/tutorial/hello-nais/hello-nais-2.md deleted file mode 100644 index b3487b89..00000000 --- a/docs/tutorial/hello-nais/hello-nais-2.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -tags: [tutorial] ---- -# Part 2 - Make it NAIS - -In the previous step, we created a repository for our application. -This part of the tutorial will show how to make your application NAIS. - -For this to happen, we need three files. - -### 1. Dockerfile - -This describes the system your application will be running on. -It includes the base image, and the commands needed to build your application. -This is the payload you are requesting NAIS to run. -We have created this file for you, as there are no changes needed for this tutorial. Check it out. - -### 2. Application manifest - -This file describes your application to the NAIS platform so that it can run it correctly and provision the resources it needs. - -Create a file called `app.yaml` in a `.nais`-folder. - -```bash -mkdir .nais -touch .nais/app.yaml -``` - -Add the following content to the file, and insert the appropriate values in the placeholders on the highlighted lines: - -???+ note ".nais/app.yaml" - - ```yaml hl_lines="6-8 11" - apiVersion: nais.io/v1alpha1 - kind: Application - - metadata: - labels: - team: - name: - namespace: - spec: - ingresses: - - https://..<>.cloud.nais.io - image: {{image}} - port: 8080 - ttl: 3h - replicas: - max: 1 - min: 1 - resources: - requests: - cpu: 50m - memory: 32Mi - ``` - -### 3. GitHub Actions workflow - -GitHub Actions uses the `Dockerfile` from step 1 and the `app.yaml` from step 2. to build and deploy your application to NAIS. - -Create a file called `main.yaml` in a `.github/workflows`-folder. - -```bash -mkdir -p .github/workflows -touch .github/workflows/main.yaml -``` - -Add the following content to the file, and insert the appropriate values in the placeholders on the highlighted lines: -???+ note ".github/workflows/main.yaml" - - ```yaml hl_lines="19 25" - name: Build and deploy - on: - push: - branches: - - main - jobs: - build_and_deploy: - name: Build, push and deploy - runs-on: ubuntu-latest - permissions: - contents: read - id-token: write - steps: - - uses: actions/checkout@v4 - - name: Push docker image to GAR - uses: nais/docker-build-push@v0 - id: docker-build-push - with: - team: # Replace - identity_provider: ${{ secrets.NAIS_WORKLOAD_IDENTITY_PROVIDER }} # Provided as Organization Secret - project_id: ${{ vars.NAIS_MANAGEMENT_PROJECT_ID }} # Provided as Organization Variable - - name: Deploy to NAIS - uses: nais/deploy/actions/deploy@v2 - env: - CLUSTER: # Replace - RESOURCE: .nais/app.yaml # This points to the file we created in the previous step - VAR: image=${{ steps.docker-build-push.outputs.image }} - ``` - -Excellent! We're now ready to deploy. :octicons-rocket-24: diff --git a/docs/tutorial/hello-nais/hello-nais-3.md b/docs/tutorial/hello-nais/hello-nais-3.md deleted file mode 100644 index c01ef128..00000000 --- a/docs/tutorial/hello-nais/hello-nais-3.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -tags: [tutorial] ---- -# Part 3 - Ship it - -Previously we've made our application and created the required files for deployment. -In this part of the tutorial we will deploy our application to NAIS. - -## 1. Authorize the repository for deployment - -This is required for the GitHub Actions workflow to be able to deploy your application. - -Visit [Console](https://console.<>.cloud.nais.io). Select your team, and visit the `Repositories` tab. -Find your repository and click `Authorize`. - -??? note "Repository not visible?" - Normally these permissions are automatically synchronized every 15 minutes, but if you don't see the repository here, force synchronization by clicking the `Refresh` button. - -## 2. Commit and push your changes - -Now that we have added the required files, it's time to commit and push them to GitHub. - - -```bash -git add . -git commit -m "FEAT: Add nais app manifest and github workflow" -git push origin main -``` - -## 3. Observe the GitHub Actions workflow - -When pushed, the GitHub Actions workflow will automatically start. You can observe the workflow by running the following command: -=== "CLI" - ```bash - gh run watch - ``` -=== "GitHub Web" - ```bash - gh repo view --web # click the "actions" tab when redirected to github.com - ``` - -## 4. Visit your application -On successful completion, we can view our application at `https://..<>.cloud.nais.io` - -Congratulations! You have now successfully deployed your first application to NAIS! -The next and most important step is to clean up after ourselves. diff --git a/docs/tutorial/hello-nais/hello-nais-4.md b/docs/tutorial/hello-nais/hello-nais-4.md deleted file mode 100644 index f955ee40..00000000 --- a/docs/tutorial/hello-nais/hello-nais-4.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -tags: [tutorial] ---- -# Part 4 - Clean up - -During this tutorial we have - -- created a github repository -- added the required files for deployment -- deployed our application to NAIS - -Now it's time to clean up after ourselves. - -## 1. Delete your repository - -When you are finished with this guide you can delete your repository: - -=== "GitHub UI" - Visit your repository on GitHub, click `Settings` -> `Delete this repository` -> `I understand the consequences, delete this repository` - -=== "GitHub CLI" - ```bash - gh repo delete / - ``` diff --git a/docs/tutorials/.pages b/docs/tutorials/.pages new file mode 100644 index 00000000..ed02d4e7 --- /dev/null +++ b/docs/tutorials/.pages @@ -0,0 +1,4 @@ +nav: +- README.md +- Hello NAIS: hello-nais.md +- ... \ No newline at end of file diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md new file mode 100644 index 00000000..3a00ed8b --- /dev/null +++ b/docs/tutorials/README.md @@ -0,0 +1,21 @@ +--- +tags: [tutorial] +hide: + - feedback + - footer +--- + +# Tutorials + +Tutorials are lessons that focuses on _learning by doing_. + +These give you hands-on experience with various parts of NAIS, where we carefully guide you each step of the way. + +
+- :octicons-rocket-24:{ .lg .middle } [**Hello NAIS**](./hello-nais.md) + + --- + + Get your first application up and running on NAIS. + +
diff --git a/docs/tutorials/hello-nais.md b/docs/tutorials/hello-nais.md new file mode 100644 index 00000000..55893437 --- /dev/null +++ b/docs/tutorials/hello-nais.md @@ -0,0 +1,225 @@ +--- +tags: [tutorial] +--- +# :wave: Hello NAIS + +This tutorial will take you through the process of getting a simple application up and running on NAIS. + +## Prerequisites + +- You have a GitHub account connected to your GitHub organization (e.g. `navikt`) +- [naisdevice installed](../operate/naisdevice/how-to/install.md) +- [Member of a NAIS team](../explanations/team.md) +- [GitHub CLI installed](https://cli.github.com/) + +???+ note "Conventions" + + Throughout this guide, we will use the following conventions: + + - `` - The name of your NAIS application (e.g. `joannas-first`) + - `` - The name of your NAIS team (e.g. `onboarding`) + - `` - Your GitHub organization (e.g. `navikt`) + - `` - The name of the environment you want to deploy to (e.g. `dev`) + + **NB!** Choose names with *lowercase* letters, numbers and dashes only. + +## :gear: Setup + +### Create your own GitHub repository + +Create your own repo using the [nais/hello-nais](https://github.com/nais/hello-nais/) as a template. + +You create a new repository through either the [GitHub UI](https://github.com/new?template_name=hello-nais&template_owner=nais) or through the GitHub CLI: + +```bash +gh repo create / --template nais/hello-nais --private --clone +``` + +```bash +cd +``` + +### Grant your team access to your repository + +Open your repository: + +```bash +gh repo view --web +``` + +Click on `Settings` -> `Collaborators and teams` -> `Add teams`. + +Select your team, and grant them the `Write` role. + +You have now successfully created your own application repository and granted your team access to it. +In the next steps we will have a closer look at the files needed to make this application NAIS! + +For this to happen, we need three files. + +### Dockerfile + +This describes the system your application will be running on. +It includes the base image, and the commands needed to build your application. +This is the payload you are requesting NAIS to run. +We have created this file for you, as there are no changes needed for this tutorial. Check it out. + +### Application manifest + +This file describes your application to the NAIS platform so that it can run it correctly and provision the resources it needs. + +Create a file called `app.yaml` in a `.nais`-folder. + +```bash +mkdir .nais +touch .nais/app.yaml +``` + +Add the following content to the file, and insert the appropriate values in the placeholders on the highlighted lines: + +???+ note ".nais/app.yaml" + + ```yaml hl_lines="6-8 11" + apiVersion: nais.io/v1alpha1 + kind: Application + + metadata: + labels: + team: + name: + namespace: + spec: + ingresses: + - https://..<>.cloud.nais.io + image: {{image}} + port: 8080 + ttl: 3h + replicas: + max: 1 + min: 1 + resources: + requests: + cpu: 50m + memory: 32Mi + ``` + +### GitHub Actions workflow + +GitHub Actions uses the `Dockerfile` from step 1 and the `app.yaml` from step 2. to build and deploy your application to NAIS. + +Create a file called `main.yaml` in a `.github/workflows`-folder. + +```bash +mkdir -p .github/workflows +touch .github/workflows/main.yaml +``` + +Add the following content to the file, and insert the appropriate values in the placeholders on the highlighted lines: +???+ note ".github/workflows/main.yaml" + + ```yaml hl_lines="19 25" + name: Build and deploy + on: + push: + branches: + - main + jobs: + build_and_deploy: + name: Build, push and deploy + runs-on: ubuntu-latest + permissions: + contents: read + id-token: write + steps: + - uses: actions/checkout@v4 + - name: Push docker image to GAR + uses: nais/docker-build-push@v0 + id: docker-build-push + with: + team: # Replace + identity_provider: ${{ secrets.NAIS_WORKLOAD_IDENTITY_PROVIDER }} # Provided as Organization Secret + project_id: ${{ vars.NAIS_MANAGEMENT_PROJECT_ID }} # Provided as Organization Variable + - name: Deploy to NAIS + uses: nais/deploy/actions/deploy@v2 + env: + CLUSTER: # Replace + RESOURCE: .nais/app.yaml # This points to the file we created in the previous step + VAR: image=${{ steps.docker-build-push.outputs.image }} + ``` + +Excellent! We're now ready to deploy :rocket: + +## :ship: Ship it + +Previously we've made our application and created the required files for deployment. +In this part of the tutorial we will deploy our application to NAIS. + +### Authorize the repository for deployment + +This is required for the GitHub Actions workflow to be able to deploy your application. + +Visit [Console](https://console.<>.cloud.nais.io). Select your team, and visit the `Repositories` tab. +Find your repository and click `Authorize`. + +!!! note "Repository not visible?" + + Normally these permissions are automatically synchronized every 15 minutes, but if you don't see the repository here, force synchronization by clicking the `Refresh` button. + +### Commit and push your changes + +Now that we have added the required files, it's time to commit and push them to GitHub. + + +```bash +git add . +git commit -m "FEAT: Add nais app manifest and github workflow" +git push origin main +``` + +### Observe the GitHub Actions workflow + +When pushed, the GitHub Actions workflow will automatically start. You can observe the workflow by running the following command: + +=== "CLI" + + ```bash + gh run watch + ``` + +=== "GitHub Web" + + - Visit your repository on [GitHub](https://github.com). + - Navigate to `Actions`. + - Select the latest workflow run. + +### Visit your application +On successful completion, we can view our application at `https://..<>.cloud.nais.io` + +Congratulations! You have now successfully deployed your first application to NAIS! +The next and most important step is to clean up after ourselves. + +## :broom: Clean up + +During this tutorial we have + +- created a github repository +- added the required files for deployment +- deployed our application to NAIS + +Now it's time to clean up after ourselves. + +### Delete your repository + +When you are finished with this guide you can delete your repository: + +=== "CLI" + + ```bash + gh repo delete / + ``` + +=== "GitHub Web" + + - Visit your repository on [GitHub](https://github.com). + - Navigate to `Settings`. + - At the bottom of the page, click on `Delete this repository` + - Confirm the deletion diff --git a/docs/workloads/.pages b/docs/workloads/.pages new file mode 100644 index 00000000..7e362ff9 --- /dev/null +++ b/docs/workloads/.pages @@ -0,0 +1,8 @@ +nav: +- README.md +- πŸ’‘ Explanations: explanations +- 🎯 How-To: how-to +- πŸ“š Reference: reference +- application +- job +- ... diff --git a/docs/workloads/README.md b/docs/workloads/README.md new file mode 100644 index 00000000..6a4145ec --- /dev/null +++ b/docs/workloads/README.md @@ -0,0 +1,35 @@ +--- +tags: [workloads, explanation] +--- + +# Workloads + +A core functionality of NAIS is enabling you to run the code you write. + +We support two types of workloads, _applications_ and _jobs_. + +
+ +- **Application** + + --- + An _application_ is a used for long-running processes such as an API. + + [:bulb: Learn more about applications](application/README.md) + +- **Job** + + --- + A _job_ is used for one-off or scheduled tasks meant to complete and then exit. + + [:bulb: Learn more about jobs](job/README.md) + +
+ +## What's next? + +[:bulb: The workload runtime environment](explanations/environment.md) + +[:bulb: Good practices for your workloads](explanations/good-practices.md) + +[:bulb: Zero trust on NAIS](explanations/zero-trust.md) diff --git a/docs/workloads/application/.pages b/docs/workloads/application/.pages new file mode 100644 index 00000000..41ff25cd --- /dev/null +++ b/docs/workloads/application/.pages @@ -0,0 +1,6 @@ +nav: +- README.md +- πŸ’‘ Explanations: explanations +- 🎯 How-To: how-to +- πŸ“š Reference: reference +- ... diff --git a/docs/workloads/application/README.md b/docs/workloads/application/README.md new file mode 100644 index 00000000..6be4fca6 --- /dev/null +++ b/docs/workloads/application/README.md @@ -0,0 +1,27 @@ +--- +tags: [application, explanation, workloads, services] +--- + +# Application + +A NAIS application lets you run one or more instances of a container image. + +An application is defined by its application manifest, which is a YAML file that describes how the application should be run and what resources it needs. + +Once the application manifest is applied, NAIS will set up your application as specified. If you've requested resources, NAIS will provision and configure your application to use those resources. + +## What's next? + +[:bulb: Learn more about exposing your application](explanations/expose.md) + +[:dart: Create an application](how-to/create.md) + +[:dart: Expose an application](how-to/expose.md) + +[:dart: Set up access policies for your application](../how-to/access-policies.md) + +[:dart: Communicate with another application](../how-to/communication.md) + +[:books: Complete application example](reference/application-example.md) + +[:books: Application specification](reference/application-spec.md) diff --git a/docs/explanation/exposing-application.md b/docs/workloads/application/explanations/expose.md similarity index 68% rename from docs/explanation/exposing-application.md rename to docs/workloads/application/explanations/expose.md index 87ddc2cc..1c08dc56 100644 --- a/docs/explanation/exposing-application.md +++ b/docs/workloads/application/explanations/expose.md @@ -1,3 +1,7 @@ +--- +tags: [application, explanation] +--- + # Exposing your application What good is an application if no one can reach it? @@ -5,14 +9,15 @@ What good is an application if no one can reach it? NAIS tries to to make it easy to expose your application to the correct audience. Your audience may be other applications within the same environment, or it may be humans or machines on the outside. -If your audience is other applications within the same environment, they can [communicate directly](../how-to-guides/communicating-inside-environment.md) with each other provided you have defined the necessary [access policies](../how-to-guides/access-policies.md). See the [zero trust](./zero-trust.md) explanation for more information. +If your audience is other applications within the same environment, they can [communicate directly](../../how-to/communication.md) with each other provided you have defined the necessary [access policies](../../how-to/access-policies.md). +See the [zero trust](../../explanations/zero-trust.md) explanation for more information. If you want to present your application to someone or something outside the environment, you have to expose it using an ingress. An ingress is simply an entrypoint into your application, defined by a URL. The domain of the URL controls from where your application can be reached. -There are different domains available in each environment, see the full [list of available domains for each cluster](../reference/environments.md). +There are different domains available in each environment, see the full [list of available domains for each cluster](../../reference/environments.md). You can have multiple ingresses for the same application, using the same or different domains. -If you only want to expose a subset of your application, or you are on a shared domain, you can specify a path for each individual ingress. +If you only want to expose a subset of your application, or you are on a shared domain, you can specify a path for each individual ingress. -For practical instructions, see the [how-to guide for exposing an application](../how-to-guides/exposing-an-application.md). +For practical instructions, see the [how-to guide for exposing an application](../how-to/expose.md). diff --git a/docs/workloads/application/how-to/create.md b/docs/workloads/application/how-to/create.md new file mode 100644 index 00000000..91b1e332 --- /dev/null +++ b/docs/workloads/application/how-to/create.md @@ -0,0 +1,65 @@ +--- +tags: [application, how-to] +--- + +# Create application + +This how-to guide will show you how to create a NAIS manifest for your [application](../README.md). + +## Setup + +Inside your application repository, create a `.nais`-folder. + +```bash +cd +mkdir .nais +``` + +Create a file called `app.yaml` in the `.nais`-folder. + +```bash +touch .nais/app.yaml +``` + +## Define your application + +Below is a basic example of an application manifest. + +Add the following content to the file, and insert the appropriate values in the placeholders on the highlighted lines: + +???+ note ".nais/app.yaml" + + ```yaml hl_lines="5-7 9" + apiVersion: nais.io/v1alpha1 + kind: Application + metadata: + labels: + team: + name: + namespace: + spec: + image: {{image}} # Placeholder variable to be replaced by the CI/CD pipeline + port: 8080 + replicas: + max: 2 + min: 4 + resources: + requests: + cpu: 200m + memory: 128Mi + ``` + +This application manifest represents a very basic daemon application. +You will likely want to add more configuration to your application manifest based on your needs. + +## What's next? + +:dart: [Build and deploy your application to NAIS](../../../build/how-to/build-and-deploy.md). + +:dart: [Expose your application](./expose.md). + +:books: [Application spec reference](../reference/application-spec.md). + +:books: [Full Application example](../reference/application-example.md). + +:bulb: [Good practices for NAIS workloads](../../explanations/good-practices.md). diff --git a/docs/workloads/application/how-to/delete.md b/docs/workloads/application/how-to/delete.md new file mode 100644 index 00000000..6ebd0272 --- /dev/null +++ b/docs/workloads/application/how-to/delete.md @@ -0,0 +1,24 @@ +--- +tags: [application, how-to] +--- + +# Delete your application + +## Prerequisites + +- You're part of a [NAIS team](../../../explanations/team.md) + +## Delete your application + +1. Open [NAIS console :octicons-link-external-16:](https://console.<>.cloud.nais.io) in your browser +2. Select your team +3. Select the `Apps` tab +4. Select the application that you want to delete +5. Click the `Delete` button + + You will be prompted to confirm the deletion. + If you have any resources connected to your application, these will also be listed. + + Once confirmed, the application will be permanently deleted. + +6. Make sure that you also remove any related workflows and manifests in your Git repository. diff --git a/docs/workloads/application/how-to/expose.md b/docs/workloads/application/how-to/expose.md new file mode 100644 index 00000000..5d9ff71b --- /dev/null +++ b/docs/workloads/application/how-to/expose.md @@ -0,0 +1,27 @@ +--- +tags: [application, how-to] +--- + +# Expose an application + +This guide will show you how to [expose your application to the correct audience](../explanations/expose.md). + +## Select audience + +Select the correct audience from the available [domains in your environment](../../reference/environments.md). + +## Define ingress + +Specify the desired hostname for your application in the [application manifest](../reference/application-spec.md#ingresses): + +```yaml hl_lines="4-5" title=".nais/app.yaml" +apiVersion: nais.io/v1alpha1 +kind: Application +spec: + ingresses: + - https://. +``` + +!!! tip "Specific paths" + + You can optionally specify a path for each individual ingress to only expose a subset of your application. diff --git a/docs/reference/application-example.md b/docs/workloads/application/reference/application-example.md similarity index 98% rename from docs/reference/application-example.md rename to docs/workloads/application/reference/application-example.md index 2f738316..5d9f4724 100644 --- a/docs/reference/application-example.md +++ b/docs/workloads/application/reference/application-example.md @@ -1,3 +1,7 @@ +--- +tags: [application, reference] +--- + # NAIS Application example YAML |Yes| B[Are they in the same namespace?] + A --> |No| Ingress[🎯 Expose through ingress] + B --> |Yes| InternalSameNS[🎯 Allow access in same namespace] + B --> |No| InternalOtherNS[🎯 Allow access from other namespaces] +``` + +If you define an [ingress](../reference/ingress.md), your application will be available to a given audience based on the domain. +**Access policies have no effect on ingress traffic**. This means that all traffic through an ingress is implicitly allowed. +Your workload is thus responsible for verifying requests if exposed through an ingress. + +## Outbound traffic + +For outbound traffic, you can allow access to other workloads in the same environment, or to external endpoints: + +```mermaid +graph TD + A[Is the service you want to call in the same environment?] + A --> |Yes| B[Are they in the same namespace?] + A --> |No| Internet[🎯 Allow access to external endpoint] + B --> |Yes| InternalSameNS[🎯 Allow access to same namespace] + B --> |No| InternalOtherNS[🎯 Allow access to other namespaces] +``` + +For the native NAIS services - the platform takes care of this for you. For example, when you have a [database](../../persistence/postgres/README.md), the access policies required to reach the database will be created automatically. + +## Example + +Consider a simple application which consists of a frontend and a backend, where naturally the frontend needs to communicate with the backend. + +This communication is denied by default as indicated by the red arrow. +![access-policy-1](../../assets/access-policy-1.png) + +In order to fix this, the frontend needs to allow outbound traffic to the backend by adding the following access policy. + +```yaml +spec: + accessPolicy: + outbound: + - application: backend +``` + +![access-policy-2](../../assets/access-policy-2.png) + +However - the frontend is still not allowed to make any requests to the backend. +The missing piece of the puzzle is adding an inbound policy to the backend like so: + +```yaml +spec: + accessPolicy: + inbound: + - application: frontend +``` + +![access-policy-3](../../assets/access-policy-3.png) + +Now that both applications has explicitly declared their policies, the communication is allowed. + +See more about [how to define access policies](../how-to/access-policies.md) diff --git a/docs/how-to-guides/access-policies.md b/docs/workloads/how-to/access-policies.md similarity index 92% rename from docs/how-to-guides/access-policies.md rename to docs/workloads/how-to/access-policies.md index 7cb83182..7f4f2476 100644 --- a/docs/how-to-guides/access-policies.md +++ b/docs/workloads/how-to/access-policies.md @@ -1,6 +1,10 @@ -# Access policies +--- +tags: [workloads, how-to] +--- -This guide will show you how to define [access policies](../explanation/zero-trust.md) for your [workload](../explanation/workloads/README.md). +# Set up access policies + +This guide will show you how to define [access policies](../explanations/zero-trust.md) for your [workload](../README.md). ## Receive requests from workloads in the same namespace @@ -62,7 +66,7 @@ For app `` to be able to receive incoming requests from `` ```mermaid graph LR - accTitle: Receive requests from other app in the another namespace + accTitle: Receive requests from other app in another namespace accDescr: The diagram shows two applications in different namespaces, and . Application is allowing requests from . ANOTHER-APP--"βœ…"-->MY-APP @@ -111,7 +115,7 @@ For app `` to be able to send requests to `` in the same n end ``` -## Send requests to other app in the another namespace +## Send requests to other app in another namespace For app `` to be able to send requests to `` in ``, this specification is needed for ``: @@ -185,3 +189,5 @@ For app `` to be able to send requests outside of the environment, this end end ``` + +See the [access policy reference](../reference/access-policies.md) for a list of default external endpoints. diff --git a/docs/workloads/how-to/communication.md b/docs/workloads/how-to/communication.md new file mode 100644 index 00000000..76c2d2c6 --- /dev/null +++ b/docs/workloads/how-to/communication.md @@ -0,0 +1,42 @@ +--- +tags: [workloads, how-to] +--- + +# Communicate inside the environment + +This guide will show you how to communicate with other workloads inside the same environment. + +## Prerequisites + +- Working [access policies](access-policies.md) for the workloads you want to communicate with. + +## Identify the endpoint you want to communicate with + +To identity the endpoint of the workload we are communicating with, we need to know it's `name` and what `namespace` it's running in. + +If the workload you are calling is in the same namespace, you can reach it by calling it's name directly using HTTP like so: + +```plaintext +http:// +``` + +If the workload is running in another team's namespace, you need to specify the namespace as well: + +```plaintext +http://. +``` + +With this endpoint, you can now call the workload using HTTP from your own workload. + +{% if tenant() == "nav" %} + +!!! info "Note for on-prem" + If your workload has [webproxy](../application/reference/application-spec.md#webproxy) enabled, you should use the full hostname for all service discovery calls: + + ```text + http://..svc.nais.local + ``` + + This is to ensure that your workload does not attempt to perform these in-cluster calls through the proxy, as the environment variable `NO_PROXY` includes `*.local`. + +{% endif %} diff --git a/docs/workloads/job/.pages b/docs/workloads/job/.pages new file mode 100644 index 00000000..f092fbf6 --- /dev/null +++ b/docs/workloads/job/.pages @@ -0,0 +1,5 @@ +nav: +- README.md +- 🎯 How-To: how-to +- πŸ“š Reference: reference +- ... diff --git a/docs/workloads/job/README.md b/docs/workloads/job/README.md new file mode 100644 index 00000000..419696c7 --- /dev/null +++ b/docs/workloads/job/README.md @@ -0,0 +1,23 @@ +--- +tags: [job, explanation, workloads, services] +--- + +# NAIS job + +A NAIS job is used for tasks meant to complete and then exit. This can either run as a one-off task or on a schedule, like a [cron job](https://en.wikipedia.org/wiki/Cron). + +A job is defined by its job manifest, which is a YAML file that describes how the job should be run and what resources it needs. + +Once the job manifest is applied, NAIS will set up your job as specified. If you've requested resources, NAIS will provision and configure your job to use those resources. + +## What's next? + +[:dart: Create a job](how-to/create.md) + +[:dart: Set up access policies for your workload](../how-to/access-policies.md) + +[:dart: Communicate with another workload](../how-to/communication.md) + +[:books: Complete job example](reference/naisjob-example.md) + +[:books: Job specification](reference/naisjob-spec.md) diff --git a/docs/workloads/job/how-to/create.md b/docs/workloads/job/how-to/create.md new file mode 100644 index 00000000..9c741d9a --- /dev/null +++ b/docs/workloads/job/how-to/create.md @@ -0,0 +1,57 @@ +--- +tags: [job, how-to] +--- + +# Create job + +This how-to guide will show you how to create a NAIS manifest for your [job](../README.md). + +## Setup + +Inside your job repository, create a `.nais`-folder. + +```bash +cd +mkdir .nais +``` + +Create a file called `job.yaml` in the `.nais`-folder. + +```bash +touch .nais/job.yaml +``` + +## Define your job + +Below is a basic example of an job manifest. + +Add the following content to the file, and insert the appropriate values in the placeholders on the highlighted lines: + +???+ note ".nais/app.yaml" + + ```yaml hl_lines="5-7 9" + apiVersion: nais.io/v1 + kind: Naisjob + metadata: + labels: + team: + name: + namespace: + spec: + schedule: "0 * * * *" # Runs every hour + image: {{image}} # Placeholder variable to be replaced by the CI/CD pipeline + resources: + requests: + cpu: 200m + memory: 128Mi + ``` + +This job manifest will run your code every hour. If you want to run your job only once, you can remove the `schedule` field. + +## What's next? + +:dart: [Build and deploy your job to NAIS](../../../build/how-to/build-and-deploy.md). + +:books: [Job spec reference](../reference/naisjob-spec.md). + +:books: [Complete job example](../reference/naisjob-example.md). diff --git a/docs/workloads/job/how-to/delete.md b/docs/workloads/job/how-to/delete.md new file mode 100644 index 00000000..fb9f7fdf --- /dev/null +++ b/docs/workloads/job/how-to/delete.md @@ -0,0 +1,24 @@ +--- +tags: [job, how-to] +--- + +# Delete your job + +## Prerequisites + +- You're part of a [NAIS team](../../../explanations/team.md) + +## Delete your job + +1. Open [NAIS console :octicons-link-external-16:](https://console.<>.cloud.nais.io) in your browser +2. Select your team +3. Select the `Job` tab +4. Select the job that you want to delete +5. Click the `Delete` button + + You will be prompted to confirm the deletion. + If you have any resources connected to your job, these will also be listed. + + Once confirmed, the job will be permanently deleted. + +6. Make sure that you also remove any related workflows and manifests in your Git repository. diff --git a/docs/reference/naisjob-example.md b/docs/workloads/job/reference/naisjob-example.md similarity index 99% rename from docs/reference/naisjob-example.md rename to docs/workloads/job/reference/naisjob-example.md index 20e409e0..95be678e 100644 --- a/docs/reference/naisjob-example.md +++ b/docs/workloads/job/reference/naisjob-example.md @@ -9,7 +9,7 @@ This is a complete example of an `Naisjob` resource. -For an in-depth explanation of each field, head over to the [reference documentation](./naisjob-spec.md). +For an in-depth explanation of each field, head over to the [reference documentation](naisjob-spec.md). ``` yaml apiVersion: nais.io/v1 kind: Naisjob diff --git a/docs/reference/naisjob-spec.md b/docs/workloads/job/reference/naisjob-spec.md similarity index 100% rename from docs/reference/naisjob-spec.md rename to docs/workloads/job/reference/naisjob-spec.md diff --git a/docs/workloads/reference/access-policies.md b/docs/workloads/reference/access-policies.md new file mode 100644 index 00000000..86417e17 --- /dev/null +++ b/docs/workloads/reference/access-policies.md @@ -0,0 +1,17 @@ +--- +tags: [workloads, reference] +--- + +# Access policies + +Default hosts that are added and accessible for every workload: + +| Host / service | Port | Protocol | +|-----------------------------|------|-----------| +| `kube-dns` | 53 | UDP / TCP | +| `metadata.google.internal` | 80 | TCP | +| `private.googleapis.com` | 443 | TCP | +| `login.microsoftonline.com` | 443 | TCP | +| `graph.microsoft.com` | 443 | TCP | +| `aivencloud.com` | 443 | TCP | +| `unleash.nais.io` | 443 | TCP | diff --git a/docs/workloads/reference/default-variables.md b/docs/workloads/reference/default-variables.md new file mode 100644 index 00000000..3dd7c257 --- /dev/null +++ b/docs/workloads/reference/default-variables.md @@ -0,0 +1,15 @@ +--- +tags: [workloads, reference] +--- + +# Default workload variables + +These environment variables will be injected into your workload container + +| variable | example | source | +|:--------------------|:-------------------------|:-------------------------------------------------| +| `NAIS_APP_NAME` | `myapp` | metadata.name from app.yaml | +| `NAIS_NAMESPACE` | `default` | metadata.namespace from app.yaml | +| `NAIS_APP_IMAGE` | `navikt/myapp:69` | spec.image from app.yaml | +| `NAIS_CLUSTER_NAME` | `prod` | which environment you are running in | +| `NAIS_CLIENT_ID` | `prod-fss:default:myapp` | concatenation of cluster, namespace and app name | diff --git a/docs/workloads/reference/environments.md b/docs/workloads/reference/environments.md new file mode 100644 index 00000000..a4f2f860 --- /dev/null +++ b/docs/workloads/reference/environments.md @@ -0,0 +1,108 @@ +--- +tags: [workloads, reference] +--- + +# Environments + +This is a overview over the different environments and their available domains. + +We also enumerate the external IPs used by the environments, so that you can provide them to services that require IP allow-listing. + +{% if tenant() == "nav" %} +## Google Cloud Platform (GCP) + +### dev-gcp + +#### Ingress domains + +| domain | accessible from | +|:-------------------|:-----------------------------------------------------------------------------| +| ekstern.dev.nav.no | internet, URLs containing `/metrics`, `/actuator` or `/internal` are blocked | +| intern.dev.nav.no | NAV internal networks (including [naisdevice]) | +| ansatt.dev.nav.no | internet, but only accessible by authenticated humans on compliant devices | + +See [explanation for exposing application][expose-app] for more information. + +#### External IPs + +- 35.228.4.248 +- 34.88.219.93 +- 35.228.165.176 + +### prod-gcp + +#### Ingress domains + +| domain | accessible from | +|:--------------|:---------------------------------------------------------------------------| +| nav.no | URLs containing `/metrics`, `/actuator` or `/internal` are blocked | +| intern.nav.no | NAV internal networks (including [naisdevice]) | +| ansatt.nav.no | internet, but only accessible by authenticated humans on compliant devices | + +See [explanation for exposing application][expose-app] for more information. + +#### External IPs + +- 35.228.235.189 +- 35.228.12.134 +- 35.228.189.194 + + +## On-prem + +!!! warning + + This is a legacy environment, and is not recommended for new workloads. + +### dev-fss + +#### Ingress domains + +| domain | accessible from | description | +|:--------------------|:----------------|:-----------------------------------------------------------------------------------------------------| +| intern.dev.nav.no | [naisdevice] | development ingress for internal applications. Also available in dev-gcp, use this to ease migration | +| dev-fss-pub.nais.io | GCP | See [How do I reach an application found on-premises from my application in GCP?][on-prem] | + +### prod-fss + +#### Ingress domains + +| domain | accessible from | description | +|:---------------------|:----------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| intern.nav.no | [naisdevice] | ingress for internal applications (supersedes nais.adeo.no). Also available in prod-gcp, use this to ease migration. Requires [JITA][naisdevice-jita] to `onprem-k8s-prod` | +| prod-fss-pub.nais.io | GCP | See [How do I reach an application found on-premises from my application in GCP?][on-prem] | + +[on-prem]: ../explanations/migrating-to-gcp.md#how-do-i-reach-an-application-found-on-premises-from-my-application-in-gcp + +{% endif %} +{% if tenant() == "ssb" %} +### staging + +#### Domains + +| domain | accessible from | description | +|:-----------------------------------|:-------------------------|:------------------------------------------------------------------------------------------------------------------| +| external.staging.ssb.cloud.nais.io | internet | ingress for applications exposed to internet. URLs containing `/metrics`, `/actuator` or `/internal` are blocked. | +| staging.ssb.cloud.nais.io | [naisdevice][naisdevice] | ingress for internal applications | + +#### External/outbound IPs + +- 34.88.116.202 + +### prod + +#### Domains + +| domain | accessible from | description | +|:--------------------------------|:----------------|:------------------------------------------------------------------------------------------------------------------| +| external.prod.ssb.cloud.nais.io | internet | ingress for applications exposed to internet. URLs containing `/metrics`, `/actuator` or `/internal` are blocked. | +| prod.ssb.cloud.nais.io | [naisdevice] | ingress for internal applications | + +#### External/outbound IPs + +- 34.88.47.40 +{% endif %} + +[naisdevice]: ../../operate/naisdevice/README.md +[naisdevice-jita]: ../../operate/naisdevice/explanations/jita.md +[expose-app]: ../../workloads/application/explanations/expose.md diff --git a/docs/reference/ingress.md b/docs/workloads/reference/ingress.md similarity index 70% rename from docs/reference/ingress.md rename to docs/workloads/reference/ingress.md index ea1680c2..e3b03d6e 100644 --- a/docs/reference/ingress.md +++ b/docs/workloads/reference/ingress.md @@ -1,8 +1,12 @@ +--- +tags: [workloads, reference] +--- + # Ingress traffic -Ingress traffic is traffic that is directed to your application from the Internet. This is done by configuring the [`ingresses`][nais-ingress] block in your NAIS application yaml manifest with the domains you want your application to receive traffic from. +Ingress traffic is traffic that is directed to your application from outside the environment. This is done by configuring the [`ingresses`][nais-ingress] block in your NAIS application yaml manifest with the domains you want your application to receive traffic from. -[nais-ingress]: https://doc.nais.io/nais-application/application/#ingresses +[nais-ingress]: ../application/reference/application-spec.md#ingresses ```mermaid graph LR @@ -38,7 +42,7 @@ You can tweak the Ingress configuration by specifying certain [Kubernetes annota [kubernetes-annotations]: https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/ [nginx-ingress-annotations]: https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/ -[service-discovery]: https://doc.nais.io/clusters/service-discovery/ +[service-discovery]: ../how-to/communication.md As the Nginx ingress documentation states, these parameters are set on the Ingress object. However, Naiserator will copy these parameters from your Application spec. @@ -106,7 +110,7 @@ All requests to your application via ingress will result in metrics being emitte ??? info "Ingress metrics label descriptions" | Label | Description | - | ----------- | ------------------------------ | + |-------------|--------------------------------| | `status` | HTTP status code | | `method` | HTTP method | | `host` | Host header (domain) | @@ -116,7 +120,7 @@ All requests to your application via ingress will result in metrics being emitte ### Uptime probes -All ingresses will automatically have uptime probes enabled on them. This probe will directed at the [application's readiness endpoint](./application-spec.md#readiness) using a HTTP GET request. A probe is considered successful if the HTTP status code is `2xx` or `3xx`. The probe is considered failed if the HTTP status code is `4xx` or `5xx`. +All ingresses will automatically have uptime probes enabled on them. This probe will directed at the [application's readiness endpoint](../application/reference/application-spec.md#readiness) using a HTTP GET request. A probe is considered successful if the HTTP status code is `2xx` or `3xx`. The probe is considered failed if the HTTP status code is `4xx` or `5xx`. You can query the uptime probe status using the following PromQL query: @@ -148,29 +152,40 @@ Percentage of `5xx` errors to the `myapp` application as a ratio of total reques ) ``` +{% if tenant() == "nav" %} + ## Ingress access logs Request access logs from nginx ingress controller are automatically collected and stored in Kibana. Here are pre-configured queries for the controller logs in the following clusters: -| Kibana | Grafana Loki | -| ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [dev-gcp](https://logs.adeo.no/app/discover#/view/1638d780-3369-11ed-b3e8-d969437dd878?_g=()) | [dev-gcp](https://grafana.nav.cloud.nais.io/explore?schemaVersion=1&panes=%7B%224fy%22%3A%7B%22datasource%22%3A%22P7BE696147D279490%22%2C%22queries%22%3A%5B%7B%22refId%22%3A%22A%22%2C%22expr%22%3A%22%7Bnamespace%3D%5C%22nais-system%5C%22%2C+app%3D%5C%22nais-ingress%5C%22%7D+%7C+json%22%2C%22queryType%22%3A%22range%22%2C%22datasource%22%3A%7B%22type%22%3A%22loki%22%2C%22uid%22%3A%22P7BE696147D279490%22%7D%2C%22editorMode%22%3A%22builder%22%7D%5D%2C%22range%22%3A%7B%22from%22%3A%22now-1h%22%2C%22to%22%3A%22now%22%7D%7D%7D&orgId=1) | -| [prod-gcp](https://logs.adeo.no/app/discover#/view/1d10b410-3369-11ed-b3e8-d969437dd878?_g=()) | [prod-gcp](https://grafana.nav.cloud.nais.io/explore?schemaVersion=1&panes=%7B%224fy%22%3A%7B%22datasource%22%3A%22PD969E40991D5C4A8%22%2C%22queries%22%3A%5B%7B%22refId%22%3A%22A%22%2C%22expr%22%3A%22%7Bnamespace%3D%5C%22nais-system%5C%22%2C+app%3D%5C%22nais-ingress%5C%22%7D+%7C+json%22%2C%22queryType%22%3A%22range%22%2C%22datasource%22%3A%7B%22type%22%3A%22loki%22%2C%22uid%22%3A%22PD969E40991D5C4A8%22%7D%2C%22editorMode%22%3A%22builder%22%7D%5D%2C%22range%22%3A%7B%22from%22%3A%22now-1h%22%2C%22to%22%3A%22now%22%7D%7D%7D&orgId=1) | -| [dev-fss](https://logs.adeo.no/app/discover#/view/e7562030-3368-11ed-b3e8-d969437dd878?_g=()) | - | -| [prod-fss](https://logs.adeo.no/app/discover#/view/00c05220-3369-11ed-b3e8-d969437dd878?_g=()) | - | +| Kibana | Grafana Loki | +|-----------------------------|---------------------------| +| [dev-gcp][dev-gcp-kibana] | [dev-gcp][dev-gcp-loki] | +| [prod-gcp][prod-gcp-kibana] | [prod-gcp][prod-gcp-loki] | +| [dev-fss] | - | +| [prod-fss] | - | + +[dev-gcp-kibana]: https://logs.adeo.no/app/discover#/view/1638d780-3369-11ed-b3e8-d969437dd878?_g=() +[prod-gcp-kibana]: https://logs.adeo.no/app/discover#/view/1d10b410-3369-11ed-b3e8-d969437dd878?_g=() +[dev-fss]: https://logs.adeo.no/app/discover#/view/e7562030-3368-11ed-b3e8-d969437dd878?_g=() +[prod-fss]: https://logs.adeo.no/app/discover#/view/00c05220-3369-11ed-b3e8-d969437dd878?_g=() +[dev-gcp-loki]: https://grafana.nav.cloud.nais.io/explore?schemaVersion=1&panes=%7B%224fy%22%3A%7B%22datasource%22%3A%22P7BE696147D279490%22%2C%22queries%22%3A%5B%7B%22refId%22%3A%22A%22%2C%22expr%22%3A%22%7Bnamespace%3D%5C%22nais-system%5C%22%2C+app%3D%5C%22nais-ingress%5C%22%7D+%7C+json%22%2C%22queryType%22%3A%22range%22%2C%22datasource%22%3A%7B%22type%22%3A%22loki%22%2C%22uid%22%3A%22P7BE696147D279490%22%7D%2C%22editorMode%22%3A%22builder%22%7D%5D%2C%22range%22%3A%7B%22from%22%3A%22now-1h%22%2C%22to%22%3A%22now%22%7D%7D%7D&orgId=1 +[prod-gcp-loki]: https://grafana.nav.cloud.nais.io/explore?schemaVersion=1&panes=%7B%224fy%22%3A%7B%22datasource%22%3A%22PD969E40991D5C4A8%22%2C%22queries%22%3A%5B%7B%22refId%22%3A%22A%22%2C%22expr%22%3A%22%7Bnamespace%3D%5C%22nais-system%5C%22%2C+app%3D%5C%22nais-ingress%5C%22%7D+%7C+json%22%2C%22queryType%22%3A%22range%22%2C%22datasource%22%3A%7B%22type%22%3A%22loki%22%2C%22uid%22%3A%22PD969E40991D5C4A8%22%7D%2C%22editorMode%22%3A%22builder%22%7D%5D%2C%22range%22%3A%7B%22from%22%3A%22now-1h%22%2C%22to%22%3A%22now%22%7D%7D%7D&orgId=1 ### Log fields description | Field | Description | -| ------------------- | ---------------------------------------------------------------------------------------------- | +|---------------------|------------------------------------------------------------------------------------------------| | `message` | HTTP request on the following format: "`method` `path` `httpVersion`" | | `response_code` | HTTP response code from nginx | | `x_upstream_name` | The application receiving the request on the following format "`namespace`-`app-name`-`port`" | | `x_upstream_status` | HTTP response code from the application | | `x_request_id` | Unique request ID used for correlating further requests from the application to other services | +{% endif %} + ### Find _your_ access logs In order to find your team's application access logs, you need to filter on the following fields: @@ -221,7 +236,7 @@ If `response_code` and `x_upstream_status` are the same it means that the applic Here are some suggestions depending on what http status code you might recieve from nginx: | Code | Suggestion | -| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +|--------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `400 Bad Request` | If nginx returns `401` error with no further explanation and there is no `x_upstream_name` it means that nginx received an invalid request before it could be sent to the backend. One of the most common problems is duplicate `Authorization` headers. | | `413 Request Entity Too Large` | If nginx return `413` error it means that the request body is too large. This can be caused by a large file upload or a large request body. The solution is to add the `proxy-body-size` ingress parameter to an appropriate size. | | `502 Bad Gateway` | If nginx return `502` error but the application is returning a `2xx` status code it might be caused by large response headers often cookies. The solution is the add the `proxy-buffer-size` to an appropriate size. | diff --git a/docs/reference/json-schema.md b/docs/workloads/reference/json-schema.md similarity index 98% rename from docs/reference/json-schema.md rename to docs/workloads/reference/json-schema.md index 2328a247..b63fa563 100644 --- a/docs/reference/json-schema.md +++ b/docs/workloads/reference/json-schema.md @@ -1,3 +1,7 @@ +--- +tags: [workloads, reference] +--- + # Validation and autocompletion in editors We expose two JSON schemas intended for use with editors to help the developer experience. diff --git a/flake.lock b/flake.lock index b69d3283..4adef621 100644 --- a/flake.lock +++ b/flake.lock @@ -2,11 +2,11 @@ "nodes": { "nixpkgs": { "locked": { - "lastModified": 1712235118, - "narHash": "sha256-h0Lsxhjcj1KJvsk6w8whaq7SLaRPPctnNMXa7nuCmGA=", + "lastModified": 1715676189, + "narHash": "sha256-ZQP+LtWbvf+rq09oKU5TkVJ0U7raUesRCn5nPh3h0Ng=", "owner": "NixOS", "repo": "nixpkgs", - "rev": "03a8f494df333933801dfe9d07412d602ecded24", + "rev": "2b6ad513c196adc8d7ed353f0c38430ad1cc88b1", "type": "github" }, "original": { diff --git a/flake.nix b/flake.nix index c51ff48e..b0517408 100644 --- a/flake.nix +++ b/flake.nix @@ -1,5 +1,5 @@ { - description = "Python for docs"; + description = "dev env for docs"; # Flake inputs inputs = { @@ -26,15 +26,10 @@ # Development environment output devShells = forAllSystems ({ pkgs }: { default = - let - # Use Python 3.10 - python = pkgs.python311; - in pkgs.mkShell { - # The Nix packages provided in the environment - packages = [ - # Python plus helper tools - python pkgs.poetry + packages = with pkgs; [ + python311 + poetry ]; }; }); diff --git a/mkdocs.yml b/mkdocs.yml index 2c21f03d..a74b4a8a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -27,6 +27,7 @@ theme: - navigation.footer - navigation.instant - navigation.indexes + - navigation.sections - search.suggest - search.highlight - search.share @@ -69,7 +70,7 @@ extra_css: plugins: - awesome-pages - tags: - tags_file: reference/tags.md + tags_file: ./tags.md - macros: j2_variable_start_string: "<<" j2_variable_end_string: ">>" @@ -79,23 +80,23 @@ plugins: enable_creation_date: true type: timeago strict: false + enabled: !ENV [CI, false] - redirects: redirect_maps: - 'addons/unleash-next.md': 'explanation/feature-toggling.md' - 'addons/unleash.md': 'explanation/feature-toggling.md' - 'observability/README.md': 'explanation/observability/README.md' - 'observability/alerts.md': 'explanation/observability/alerting.md' - 'observability/frontend/README.md': 'explanation/observability/frontend.md' - 'observability/grafana.md': 'explanation/observability/README.md' - 'observability/logs/README.md': 'explanation/observability/logging.md' - 'observability/logs/examples.md': 'explanation/observability/logging.md' - 'observability/metrics.md': 'explanation/observability/metrics.md' - 'observability/tracing.md': 'explanation/observability/tracing.md' - 'security/salsa/salsa.md': 'security/salsa/README.md' - 'addons/wonderwall.md': 'security/auth/wonderwall.md' - 'device/update.md': 'how-to-guides/naisdevice/update.md' - 'how-to-guides/observability/tracing/otel-tracing.md': 'how-to-guides/observability/auto-instrumentation.md' - 'reference/observability/otel/tracing.md': 'reference/observability/auto-config.md' + "addons/unleash-next.md": "services/feature-toggling.md" + "addons/unleash.md": "services/feature-toggling.md" + "observability/alerts.md": "observability/alerting/README.md" + "explanation/observability/alerting.md": "observability/alerting/README.md" + "observability/grafana.md": "observability/README.md" + "observability/logs/README.md": "observability/logging/README.md" + "observability/logs/examples.md": "observability/logging/README.md" + "security/salsa/salsa.md": "services/salsa.md" + "addons/wonderwall.md": "security/auth/wonderwall.md" + "device/update.md": "operate/naisdevice/how-to/update.md" + "device/install.md": "operate/naisdevice/how-to/install.md" + "how-to-guides/observability/tracing/otel-tracing.md": "observability/how-to/auto-instrumentation.md" + "reference/observability/otel/tracing.md": "observability/reference/auto-config.md" + "deployment.md": "build/README.md" markdown_extensions: - toc: permalink: True diff --git a/tenants/nav/how-to-guides/oci-migration.md b/tenants/nav/build/how-to/oci-migration.md similarity index 90% rename from tenants/nav/how-to-guides/oci-migration.md rename to tenants/nav/build/how-to/oci-migration.md index dcb319ce..f233afdd 100644 --- a/tenants/nav/how-to-guides/oci-migration.md +++ b/tenants/nav/build/how-to/oci-migration.md @@ -1,3 +1,7 @@ +--- +tags: [build, deploy, how-to] +--- + # How to migrate from GitHub Container Registry (GHCR) to Google Artifact Registry (GAR) ## Migrate @@ -119,9 +123,6 @@ as `needs.build.outputs.image` VAR: image=${{ needs.build.outputs.image }} ``` -If you wish to refer to the image later, please consult the guide -on [Image registry](https://doc.nais.io/guides/application/#step-6-push-your-image-to-our-image-registry). - #### NAIS Salsa (SLSA - Supply Chain Levels for Software Artifacts) [SLSA](https://slsa.dev/) is short for Supply chain Levels for Software Artifacts pronounced salsa. @@ -130,8 +131,8 @@ enhancing integrity, and securing both packages and infrastructure within our pr The `nais/docker-build-push` action automatically signs your image with [cosign](https://github.com/sigstore/cosign), and uploads the attestation, the result can be reviewed in your team tab -in [NAIS Console](https://console.nav.cloud.nais.io). -For more information about Salsa, please refer to [NAIS Salsa](https://docs.nais.io/security/salsa/salsa/). +in [NAIS Console](https://console.<>.cloud.nais.io). +For more information about Salsa, please refer to [NAIS Salsa](../../services/salsa.md). #### Workflow permissions @@ -163,7 +164,7 @@ to [The GitHub Blog Post](https://github.blog/changelog/2021-04-20-github-action The use of `secrets.NAIS_DEPLOY_APIKEY` is deprecated, and will be removed in the future. For more information on how to authorize your workflow, please refer -to [Authorize your workflow](https://docs.nais.io/deployment/github-action/?h=deploy#1-authorize-your-github-repository-for-deployment) +to [Authorize your workflow](build-and-deploy.md#1-authorize-your-github-repository-for-deployment) ### Finalized workflow @@ -217,6 +218,4 @@ will not run unless the `build` job is successful. That is why we can reference ## Related documentation -To get more details about deploying to NAIS, please -refer: [Deploy an application](https://doc.nais.io/guides/application/#deploying-an-application) -and [Deploy with GitHub Actions](https://doc.nais.io/deployment/?h=deploy+to#nais-deploy) +- :dart: [Build and deploy with Github Actions](build-and-deploy.md) diff --git a/tenants/nav/explanation/migrating-databases-to-gcp.md b/tenants/nav/explanation/migrating-databases-to-gcp.md deleted file mode 100644 index a0bb7919..00000000 --- a/tenants/nav/explanation/migrating-databases-to-gcp.md +++ /dev/null @@ -1,161 +0,0 @@ -# Migrating databases to GCP - -## Migrating databases to GCP postgreSQL - -Suggested patterns for moving on-prem databases to GCP postgreSQL. - -Disclaimer: These are options for migrations to GCP postgreSQL. Others may work better for your team. - -## Prerequisites - -The team needs to update their ROS and PVK analysis to migrate to GCP. Refer to the [ROS](../reference/legal/app-ros.md) and [PVK](../reference/legal/app-pvk.md). - -See database creation in GCP in [Google Cloud Platform persistence](../how-to-guides/persistence/postgres/README.md). - -## Migration paths available - -### From on-premise Oracle - -#### Replication migration using migration application - -Create a simple migration application that supports writing data to the new database. Using requests sent to this application you can populate the new postgreSQL database. - -Rewrite the oracle DDL scripts to postgreSQL. If your oracle database contains specific oracle procedures or functions, that do not exist in postgreSQL, they will have to be recreated in some other way. There are tools available to help ease this rewrite, for example [ora2pg](http://ora2pg.darold.net/start.html). Create the postgreSQL database in GCP and start deploy the application to GCP with the empty database and let flyway \(or other database versioning software\) create the DDLs. - -Create migration app as a container in the same pod as the database application \(this is to avoid permission issues using the same database\). This migration application only handles the data transfer from the oracle database to postgreSQL in GCP. - -Examples: - -* [PAM Stillingsregistrering API Migration](https://github.com/navikt/pam-stillingsregistrering-api-migration/#pam-stillingsregistrering-api-migration) (documentation and code) -* [PAM AD Migration](https://github.com/navikt/pam-ad-migration) (no documentation, just code) -* [Rekrutteringsbistand migration](https://github.com/navikt/rekrutteringsbistand-kandidat-api-migrering) (not using JPA for easier code and less memory-intensive data handling, but as-is only suitable on-premise migration) - -Trigger migration from command line \(or use another form of trigger\) and read the data from a feed or kafka. - -Pros: - -* No downtime -* Live synchronization between on-premise and GCP -* Migration controlled entirely by team -* Migration can be stopped and restarted at any moment - -Cons: - -* Can be slow if large amounts of data are to be transferred, if this is the case use kafka for the streaming process instead -* Can be tricky for complex databases - -!!! note - This procedure is also valid for on-premise postgreSQL migration, and even simpler as no rewrite is necessary. - -### From on-premise postgreSQL - -#### Migration using pg\_dump - -This method is suitable for applications that can have the database in read-only or application that allow for some downtime. It requires that the database instance and DDLs are created up front \(i.e. deploy your application in GCP and let flyway create DDLs\): - -Use docker container image with psql and cloudsdk: [GCP migration image](https://github.com/navikt/gcp-migrering). This image let you do all the following actions from one place. You can either use the manual described below or the migration_data.sh script in the repository. - -In any case you need to create a secret in your namespace containing the Google SA you want to use to do the migration. Add the token to the secret.yaml file and apply it in your namespace. - -Deploy the pod into on-premise cluster that can connect to the database - -```shell -kubectl apply -f https://raw.githubusercontent.com/navikt/gcp-migrering/main/gcloud.yaml -``` - -`exec` into that pod - -```shell -kubectl exec -it gcloud -- /bin/bash -``` - -Log in to gcloud with your own NAV-account - -```shell -gcloud auth login -``` - -Configure the project id \(find project id with `gcloud projects list --filter team`\) - -```shell -gcloud config set project -``` - -Create a GCP bucket. You will need the `roles/storage.admin` IAM role for the required operations on the bucket. - -```shell -gsutil mb -l europe-north1 gs:// -``` - -Find the GCP service account e-mail \(the instance id is specified in your `nais.yaml` file\) - -```shell -gcloud sql instances describe | yq r - serviceAccountEmailAddress -``` - -Set the objectAdmin role for the bucket \(with the previous e-mail\) - -```shell -gsutil iam ch serviceAccount::objectAdmin gs:/// -``` - -Use `pg_dump` to create the dump file. Notes: - -- Make sure that you stop writes to database before running `pg_dump`. -- Get a [database user from Vault](https://github.com/navikt/utvikling/blob/main/docs/teknisk/Vault.md#--hente-ut-postgresql-credentials-til-en-utvikler). -- If the database in GCP already has the `flyway_schema_history` table, - you might want to exclude the equivalent table in the dump by using the `--exclude-table=flyway_schema_history` option. - -```shell -pg_dump \ - -h \ - -d \ - -U \ - --format=plain --no-owner --no-acl --data-only -Z 9 > dump.sql.gz -``` - -Copy the dump file to GCP bucket - -```shell -gsutil -o GSUtil:parallel_composite_upload_threshold=150M -h "Content-Type:application/x-gzip" cp dump.sql.gz gs:/// -``` - -Import the dump into the GCP postgreSQL database. Notes: - -- You need the `roles/cloudsql.admin` IAM role in order to perform the import. -- The `user` in the command below should be a GCP SQL Instance user. -- If the GCP Postgres database has any existing tables or sequences, make sure that the `user` has all required grants for these. - -```shell -gcloud sql import sql gs:///dump.sql.gz \ - --database= \ - --user= -``` - -Verify that the application is behaving as expected and that the data in the new database is correct. Finally we need to switch loadbalancer to route to the GCP application instead of the on-premise equivalent. - -Delete the bucket in GCP after migration is complete - -```shell -gsutil -m rm -r gs:// -gsutil rb gs:// -``` - -Pros: - -* Easy and relatively fast migration path -* No need for separate migration application or streams to populate database - -Cons: - -* Requires downtime for the application, or at least no writes to database -* Requires node with access to on-premise database and GCP buckets - -#### Replication migration using migration application - -Same procedure as for Oracle. - -#### Replication migration using pgbouncer - -Not available as of now. - diff --git a/tenants/nav/explanation/migrating-to-gcp.md b/tenants/nav/explanation/migrating-to-gcp.md deleted file mode 100644 index 9aa1fc5c..00000000 --- a/tenants/nav/explanation/migrating-to-gcp.md +++ /dev/null @@ -1,204 +0,0 @@ -# Migrating to GCP - -## Why migrate our application\(s\)? - -* Access to self-service [Google-managed buckets](../how-to-guides/persistence/buckets/create.md) and [Postgres databases](../how-to-guides/persistence/postgres/README.md). -* Access to Google Cloud features. -* [Zero Trust security model](zero-trust.md) instead of FSS/SBS zone model. -* Cost efficient and future proof. - -## Prerequisites - -* The team needs to update their ROS and PVK analysis to migrate to GCP. -* Read this [roles and responsibilites](../reference/legal/roles-responsibilities.md) - -### Security - -Our GCP clusters use a zero trust security model, implying that the application must specify both incoming and outgoing connections in order to receive or send traffic at all. This is expressed using [access policies](../how-to-guides/access-policies.md). - -### Privacy - -Google is cleared to be a data processor for personally identifiable information \(PII\) at NAV. However, before your team moves any applications or data to GCP the following steps should be taken: - -1. Verify that you have a valid and up-to-date PVK for your application. This document should be [tech stack agnostic](../reference/legal/app-pvk.md) and as such does not need to be changed to reflect the move to GCP. -2. If the application stores any data in GCP, update [Behandlingskatalogen](https://behandlingskatalog.nais.adeo.no/) to reflect that Google is a data processor. - -### ROS - -The ROS analysis for the team's applications need to be updated to reflect any changes in platform components used. For example, if your team has any specific measures implemented to mitigate risks related to "Kode 6 / 7 users", you should consider if these measures still apply on the new infrastructure or if you want to initiate any additional measures. When updating the ROS, please be aware that the GCP components you are most likely to use have already undergone [risk assessment by the nais team](../reference/legal/nais-ros.md) and that you can refer to these ROS documents in your own risk assessment process. - -## FAQ - -### What do we have to change? - -???+ faq "Answer" - - * Cluster name: All references to cluster name. \(Logs, grafana, deploy, etc.\) - * Secrets: are now stored as native secrets in the cluster, rather than externally in Vault. - * Namespace: If your application is in the `default` namespace, you will have to move to team namespace - * Storage: Use `GCS-buckets` instead of `s3` in GCP. Buckets, and access to them, are expressed in your [application manifest](../nais-application/example.md) - * Ingress: There are some domains that are available both on-prem and in GCP, but some differ, make sure to verify before you move. - * Postgres: A new database \(and access to it\) is automatically configured when expressing `sqlInstance` in your [application manifest](../nais-application/example.md) - - We're currently investigating the possibility of using on-prem databases during a migration window. - - * PVK: Update your existing PVK to include cloud - - [GCP compared to on-premises](migrating-to-gcp.md#gcp-compared-to-on-premises) summarizes the differences and how that may apply to your application. - -### What should we change? - -???+ faq "Answer" - - - Use [TokenX](../security/auth/tokenx.md) instead of API-GW. - - If using automatically configured [Google-managed buckets](../persistence/buckets.md) or [postgres](../how-to-guides/persistence/postgres/README.md), use [Google APIs](https://cloud.google.com/storage/docs/reference/libraries) - -### What do we not need to change? - -???+ faq "Answer" - - You do not have to make any changes to your application code. Ingresses work the same way, although some domains overlap and others are exclusive. Logging, secure logging, metrics and alerts work the same way. - -### What can we do now to ease migration to GCP later? - -???+ faq "Answer" - - - Make sure your PVK is up to date. - - Deploy your application to your team's namespace instead of `default`, as this is not available in GCP. - - Use a token auth flow between your applications. Either [TokenX](../security/auth/tokenx.md), [AAD on-behalf-of or AAD client_credentials flow](../security/auth/azure-ad/README.md) depending on your use case. This allows for a more seamless migration of your applications. E.g. if you have two apps in FSS, you can migrate one without the other. - -### What about PVK? - -???+ faq "Answer" - - A PVK is not a unique requirement for GCP, so all applications should already have one. See [about security and privacy when using platform services](../README.md#about-security-and-privacy-when-using-platform-services) for details - -### How do we migrate our database? - -???+ faq "Answer" - - See [Migrating databases to GCP](./migrating-databases-to-gcp.md). - -### Why is there no Vault in GCP? - -???+ faq "Answer" - - There is native functionality in GCP that overlap with many of the use cases that Vault have covered on-prem. Using these mechanisms removes the need to deal with these secrets at all. Introducing team namespaces allows the teams to manage their own secrets in their own namespaces without the need for IAC and manual routines. For other secrets that are not used by the application during runtime, you can use the Secrets in Console. - -### How do we migrate from Vault to NAIS Secrets? - -???+ faq "Answer" - - See the [Secrets documentation](../explanations/secrets/). - -### How do we migrate from filestorage to buckets? - -???+ faq "Answer" - - Add a bucket to your application spec Copy the data from the filestore using [s3cmd](https://s3tools.org/s3cmd) to the bucket using [gsutil](https://cloud.google.com/storage/docs/gsutil) - -### What are the plans for cloud migration in NAV? - -???+ faq "Answer" - - Both sbs clusters are now retired. NAVs strategic goal is to shut off all on-prem datacenters by the end of 2023 - -### What can we do in our GCP project? - -???+ faq "Answer" - - The teams GCP projects are primarily used for automatically generated resources \(buckets and postgres\). We're working on extending the service offering. However, additional access may be granted if required by the team - -### How long does it take to migrate? - -???+ faq "Answer" - - A minimal application without any external requirements only have to change a single configuration parameter when deploying and have migrated their application in 5 minutes. [GCP compared to on-premises](migrating-to-gcp.md#gcp-compared-to-on-premises) summarizes the differences and how that may apply to your application. - - -### We have personally identifiable and/or sensitive data in our application, and we heard about the Privacy Shield invalidation. Can we still use GCP? - -???+ faq "Answer" - - **Yes.** [NAV's evaluation of our Data Processor Agreement with Google post-Schrems II](https://navno.sharepoint.com/:w:/r/sites/Skytjenesterforvaltningsregime/_layouts/15/Doc.aspx?sourcedoc=%7BA9562232-BB00-40CB-930D-4EF254A5AD7F%7D&file=2020-10-10%20GCP%20-%20behandling%20og%20avtaler.docx&action=default&mobileredirect=true) is that it still protects us and is valid for use **given that data is stored and processed in data centers located within the EU/EEA**. If your team uses resources provisioned through NAIS, this is guaranteed by the nais team. If your team uses any other GCP services the team is responsible for ensuring that only resources within EU/EES are used \(as well as for evaluating the risk of using these services\). - - See [Laws and regulations/Application PVK](../legal/app-pvk.md) for details. - -### How do I reach an application found on-premises from my application in GCP? - -???+ faq "Answer" - - The application _on-premises_ should generally fulfill the following requirements: - - 1. Be secured with [OAuth 2.0](../security/auth/README.md). That is, either: - - a. [TokenX](../security/auth/tokenx.md), or - - b. [Azure AD](../security/auth/azure-ad/README.md) - 2. Exposed to GCP using a special ingress: - - `https://.dev-fss-pub.nais.io` - - `https://.prod-fss-pub.nais.io` - - The application _on-premises_ must then: - - 1. Add the ingress created above to the list of ingresses: - - ```yaml - spec: - ingresses: - - https://.-fss-pub.nais.io - ``` - - 2. If secured with OAuth 2.0, ensure that the application also has set up inbound access policies: - - a. [Access Policies for TokenX](../security/auth/tokenx.md#access-policies) - - b. [Access Policies for Azure AD](../security/auth/azure-ad/configuration.md#pre-authorization) - - The application _in GCP_ must then: - - 1. Add the above hosts to their [outbound external access policies](../nais-application/access-policy.md#external-services): - - ```yaml - spec: - accessPolicy: - outbound: - external: - - host: .-fss-pub.nais.io - ``` - -### How do I reach an application found on GCP from my application on-premises? - -???+ faq "Answer" - - The application in GCP must be exposed on a [matching ingress](gcp.md#accessing-the-application): - - | ingress | reachable from zone | - | :--- | :--- | - | `.intern.dev.nav.no` | `dev-fss` | - | `.intern.nav.no` | `prod-fss` | - | `.nav.no` | Internet, i.e. all clusters | - - The application on-premises should _not_ have to use webproxy to reach these ingresses. - -## GCP compared to on-premises - -| Feature | on-prem | gcp | Comment | -|:--------------------------|:-----------|:----------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| Deploy | yes | yes | different clustername when deploying | -| Logging | yes | yes | different clustername in logs.adeo.no | -| Metrics | yes | yes | same mechanism, different datasource | -| Nais app dashboard | yes | yes | new and improved in GCP | -| Alerts | yes | yes | identical | -| Secure logs | yes | yes | different clustername in logs.adeo.no | -| Kafka | yes | yes | identical | -| Secrets | Vault | Console secrets | | -| Team namespaces | yes | yes | | -| Shared namespaces | yes | no | Default namespace not available for teams in GCP | -| Health checks | yes | yes | identical | -| Ingress | yes | yes | See [environments overview](../reference/environments.md) for available domains | -| Storage | Ceph | Buckets | | -| Postgres | yes \(IAC\) | yes \(self-service\) | | -| Laptop access | yes | yes | | -| domain: dev.intern.nav.no | | yes \(Automatic\) | Wildcard DNS points to GCP load balancer | -| Access to FSS services | | yes | Identical \(either API-gw or TokenX) -| NAV truststore | yes | yes | | -| PVK required | yes | yes | amend to cover storage in cloud | -| Security | Zone Model | [zero-trust](./zero-trust.md) | | - diff --git a/tenants/nav/explanation/naisdevice.md b/tenants/nav/explanation/naisdevice.md deleted file mode 100644 index 9180ed64..00000000 --- a/tenants/nav/explanation/naisdevice.md +++ /dev/null @@ -1,12 +0,0 @@ -# naisdevice - -naisdevice is a mechanism provided by NAIS, that lets you connect to services not available on the public Internet from your machine. - -Examples of such services are: -- Access to the NAIS cluster with kubectl -- Applications on internal domains -- Internal NAIS services such as [console](https://console.<>.cloud.nais.io). - -In order to be able to connect, your machine needs to meet certain requirements. These requirements are enforced by a third-party service called [Kolide](https://kolide.com/) that is installed alongside naisdevice. - -Kolide uses Slack to communicate with you when something is wrong with your machine, guiding you through the process of fixing it. diff --git a/tenants/nav/how-to-guides/persistence/influxdb/datasource.md b/tenants/nav/how-to-guides/persistence/influxdb/datasource.md deleted file mode 100644 index bf33a2a3..00000000 --- a/tenants/nav/how-to-guides/persistence/influxdb/datasource.md +++ /dev/null @@ -1,15 +0,0 @@ -# Datasource in Grafana - -Let us know in [#nais](https://nav-it.slack.com/archives/C5KUST8N6) if you want your InfluxDB to be exposed in Grafana. -This means that everyone can access your data. -(TODO: Nav ONLY) -# Access from laptop - -With Naisdevice you have access to the _aiven-prod_ gateway. -This is a JITA (just in time access) gateway, so you need to describe why, but the access is automatically given. - -``` -influx -username avnadmin -password foo -host influx-instancename-nav-dev.aivencloud.com -port 26482 -ssl -``` - -PS: Remember to use Influxdb CLI pre v2. For example v1.8.3. \ No newline at end of file diff --git a/tenants/nav/reference/legal/app-pvk.md b/tenants/nav/legal/app-pvk.md similarity index 57% rename from tenants/nav/reference/legal/app-pvk.md rename to tenants/nav/legal/app-pvk.md index cfac968e..f16c2f0b 100644 --- a/tenants/nav/reference/legal/app-pvk.md +++ b/tenants/nav/legal/app-pvk.md @@ -1,7 +1,7 @@ # Application privacy impact assessments (PVK) -Before deploying any application that processes and/or stores data to nais, a privacy assessment \(PVK\) must be conducted. This PVK should be kept reasonably up-to-date through the life cycle of the application. Refer to the [PVK process documentation for details](https://navno.sharepoint.com/sites/intranett-personvern/SitePages/PVK.aspx) \(NAV internal link\). +Before deploying any application that processes and/or stores data to nais, a privacy assessment (PVK) must be conducted. This PVK should be kept reasonably up-to-date through the life cycle of the application. Refer to the [PVK process documentation for details](https://navno.sharepoint.com/sites/intranett-personvern/SitePages/PVK.aspx) \(NAV internal link\). -Ideally, the language in your PVK should be tech stack agnostic, meaning there will not be any need to change this document as components are changed or the application is [moved between on-premises and cloud clusters](../clusters/migrating-to-gcp.md). Any technology specific considerations belong in [the risk assessment](app-ros.md). +Ideally, the language in your PVK should be tech stack agnostic, meaning there will not be any need to change this document as components are changed or the application is [moved between on-premises and cloud clusters](../workloads/explanations/migrating-to-gcp.md). Any technology specific considerations belong in [the risk assessment](app-ros.md). For migrating applications to the cloud, a document has been prepared to aid the PVK process internal for NAV [NAIS i sky – personvern og sikkerhet. internal for NAV](https://navno.sharepoint.com/:w:/s/Skystrategi817/EcVERNkDfLlIt6s0hjSIxoQBGnyufj1ZEZABLtJ-wIdbNg?e=4%3AOj6D2G&at=9&CID=fc0f7ebb-69d8-4ceb-33f4-2778fa0dfd50) diff --git a/tenants/nav/reference/legal/app-ros.md b/tenants/nav/legal/app-ros.md similarity index 100% rename from tenants/nav/reference/legal/app-ros.md rename to tenants/nav/legal/app-ros.md diff --git a/tenants/nav/reference/legal/arkivloven.md b/tenants/nav/legal/arkivloven.md similarity index 100% rename from tenants/nav/reference/legal/arkivloven.md rename to tenants/nav/legal/arkivloven.md diff --git a/tenants/nav/reference/legal/dpa/README.md b/tenants/nav/legal/dpa/README.md similarity index 100% rename from tenants/nav/reference/legal/dpa/README.md rename to tenants/nav/legal/dpa/README.md diff --git a/tenants/nav/reference/legal/dpa/aiven-dpa.md b/tenants/nav/legal/dpa/aiven-dpa.md similarity index 78% rename from tenants/nav/reference/legal/dpa/aiven-dpa.md rename to tenants/nav/legal/dpa/aiven-dpa.md index 0b2a503b..a2030580 100644 --- a/tenants/nav/reference/legal/dpa/aiven-dpa.md +++ b/tenants/nav/legal/dpa/aiven-dpa.md @@ -4,5 +4,5 @@ NAV has, based on the Schrems II verdict that invalidated The EU-US Privacy Shie Other relevant documents: -* [Risk analysis related to the Kafka service and underlaying platform](https://apps.powerapps.com/play/f8517640-ea01-46e2-9c09-be6b05013566?ID=190) +* [Risk analysis related to the Kafka service and underlying platform](https://apps.powerapps.com/play/f8517640-ea01-46e2-9c09-be6b05013566?ID=190) diff --git a/tenants/nav/reference/legal/dpa/azure-dpa.md b/tenants/nav/legal/dpa/azure-dpa.md similarity index 100% rename from tenants/nav/reference/legal/dpa/azure-dpa.md rename to tenants/nav/legal/dpa/azure-dpa.md diff --git a/tenants/nav/reference/legal/dpa/gcp-dpa.md b/tenants/nav/legal/dpa/gcp-dpa.md similarity index 100% rename from tenants/nav/reference/legal/dpa/gcp-dpa.md rename to tenants/nav/legal/dpa/gcp-dpa.md diff --git a/tenants/nav/reference/legal/nais-pvk.md b/tenants/nav/legal/nais-pvk.md similarity index 95% rename from tenants/nav/reference/legal/nais-pvk.md rename to tenants/nav/legal/nais-pvk.md index 36688eb0..591b526f 100644 --- a/tenants/nav/reference/legal/nais-pvk.md +++ b/tenants/nav/legal/nais-pvk.md @@ -6,5 +6,5 @@ The exception to the data agnostic rule is data that the platform itself is the Thus, the only personally identifiable information (PII) that the platform processes are access logs for developers at NAV. A PVK for this data processing has been conducted. -For details on what each team's responsibilites are with respect to data processing on the platform, refer to [roles and responsibilities](./roles-responsibilities.md). +For details on what each team's responsibilites are with respect to data processing on the platform, refer to [roles and responsibilities](roles-responsibilities.md). diff --git a/tenants/nav/reference/legal/nais-ros.md b/tenants/nav/legal/nais-ros.md similarity index 100% rename from tenants/nav/reference/legal/nais-ros.md rename to tenants/nav/legal/nais-ros.md diff --git a/tenants/nav/reference/legal/roles-responsibilities.md b/tenants/nav/legal/roles-responsibilities.md similarity index 100% rename from tenants/nav/reference/legal/roles-responsibilities.md rename to tenants/nav/legal/roles-responsibilities.md diff --git a/tenants/nav/how-to-guides/observability/logs/access-secure-logs.md b/tenants/nav/observability/logging/how-to/access-secure-logs.md similarity index 83% rename from tenants/nav/how-to-guides/observability/logs/access-secure-logs.md rename to tenants/nav/observability/logging/how-to/access-secure-logs.md index 1824c88b..b407d042 100644 --- a/tenants/nav/how-to-guides/observability/logs/access-secure-logs.md +++ b/tenants/nav/observability/logging/how-to/access-secure-logs.md @@ -1,11 +1,11 @@ --- -tags: [guide] +tags: [how-to, logging] --- # Access secure logs Once everything is configured, your secure logs will be sent to the `tjenestekall-*` index in kibana. To gain access to these logs, you need to do the following: -## 1 Create an AD-group +## Create an AD-group To make sure you gain access to the proper logs, you need an AD-group connected to the nais-team. So the first thing you do is create this group. @@ -27,15 +27,16 @@ Den mΓ₯ inn i Remedy. Enheter i Nav som skal ha tilgang: . E.g (2990 - IT-AVDELINGEN) ``` -![ticket](../../assets/jira_secure_log.png) +![ticket](../../../assets/jira_secure_log.png) -## 2 Connect the AD group to your team in Kibana +## Connect the AD group to your team in Kibana -The logs your apps produces are linked with your [nais-team](../../team.md). +The logs your apps produces are linked with your [NAIS team](../../../explanations/team.md). Administrators of Kibana will create a role for your team with read rights to those logs. -Whoever is in the AD-group (created in step 1) will get the Kibana role, and can thus read all logs produced by apps belonging to the nais-team. Ask for this in the [#kibana](https://nav-it.slack.com/archives/C7T8QHXD3) Slack channel; provide the name of the AD-group and the name of your team in the message. +Whoever is in the AD-group (created in step 1) will get the Kibana role, and can thus read all logs produced by apps belonging to the team. +Ask for this in the [#kibana](https://nav-it.slack.com/archives/C7T8QHXD3) Slack channel; provide the name of the AD-group and the name of your team in the message. -## 3 Put people into the AD-group +## Put people into the AD-group This must be done by "identansvarlig". For NAV-IT employees, this is `nav.it.identhandtering@nav.no`. Send them an email and ask for access with a CC to whoever is your superior. diff --git a/tenants/nav/how-to-guides/observability/logs/audit-logs.md b/tenants/nav/observability/logging/how-to/audit-logs.md similarity index 91% rename from tenants/nav/how-to-guides/observability/logs/audit-logs.md rename to tenants/nav/observability/logging/how-to/audit-logs.md index 01dd38b7..c41dce7c 100644 --- a/tenants/nav/how-to-guides/observability/logs/audit-logs.md +++ b/tenants/nav/observability/logging/how-to/audit-logs.md @@ -1,3 +1,7 @@ +--- +tags: [how-to, logging] +--- + # Audit logs Most applications where a user processes data related to another user need to log audit statements, detailing which user did what action on which subject. These logs need to follow a specific format and be accessible by ArcSight. diff --git a/tenants/nav/how-to-guides/observability/logs/enable-secure-logs.md b/tenants/nav/observability/logging/how-to/enable-secure-logs.md similarity index 94% rename from tenants/nav/how-to-guides/observability/logs/enable-secure-logs.md rename to tenants/nav/observability/logging/how-to/enable-secure-logs.md index 1293982b..cbc783c2 100644 --- a/tenants/nav/how-to-guides/observability/logs/enable-secure-logs.md +++ b/tenants/nav/observability/logging/how-to/enable-secure-logs.md @@ -1,5 +1,5 @@ --- -tags: [guide] +tags: [how-to, logging] --- # Enable secure logs @@ -11,13 +11,13 @@ Some applications have logs with information that should not be stored with the This is guide contains a deprecated syntax for enabling secure logs. With the new syntax all logs will be sent to secure logs when enabled and will not require any special log configuration. -## 1. Prerequisites +## Prerequisites If your NAIS team has already at any point produced secure logs, you can skip this step. If your team has never before produced secure logs, before enabling them for the first time, give a warning in [#kibana](https://nav-it.slack.com/archives/C7T8QHXD3) Slack channel. There are some things that need to be adjusted before a new team can start sending. Remember to include the name of your NAIS team in the message. -## 2. Enabling secure logs [manifest](../../../reference/application-spec.md) +## Enabling secure logs [manifest](../../../workloads/application/reference/application-spec.md) ???+ note ".nais/app.yaml" @@ -27,7 +27,7 @@ If your team has never before produced secure logs, before enabling them for the enabled: true ``` -## 3. Set log rotation +## Set log rotation With secure logs enabled a directory `/secure-logs/` will be mounted in the application container. Every `*.log` file in this directory will be monitored and the content transferred to Elasticsearch. Make sure that these files are readable for the log shipper \(the process runs as uid/gid 1065\). @@ -56,7 +56,7 @@ Log files should be in JSON format as the normal application logs. Here is an ex ``` -## 4. Configure log shipping +## Configure log shipping Example configuration selecting which logs go to secure logs @@ -102,7 +102,7 @@ Example configuration selecting which logs go to secure logs ``` -## 5. Use secure logs in application +## Use secure logs in application Using the Logback config below you can log to secure logs by writing Kotlin-code like this: @@ -119,7 +119,7 @@ log.info("Non-sensitive data here") // Logging to non-secure app logs ``` See doc on [Logback filters](https://logback.qos.ch/manual/filters.html#evaluatorFilter) and [markers](https://www.slf4j.org/api/org/slf4j/MarkerFactory.html) -See [Example log configuration](../../../reference/logs-example.md) for further configuration examples. +See [Example log configuration](#example-log-configuration) for further configuration examples. ### Non-JSON logs diff --git a/tenants/nav/how-to-guides/observability/logs/kibana.md b/tenants/nav/observability/logging/how-to/kibana.md similarity index 84% rename from tenants/nav/how-to-guides/observability/logs/kibana.md rename to tenants/nav/observability/logging/how-to/kibana.md index fe8195c0..734a3299 100644 --- a/tenants/nav/how-to-guides/observability/logs/kibana.md +++ b/tenants/nav/observability/logging/how-to/kibana.md @@ -1,6 +1,6 @@ --- description: This guide will help you get started with Kibana. -tags: [guide, kibana] +tags: [how-to, logging, kibana] --- # Get started with Elastic Kibana @@ -38,6 +38,6 @@ When you open Kibana you are prompted to select a workspace, select "Nav Logs" t Once the page loads you will see an empty page with a search bar. This is the query bar, and it is used to search for logs. You can use the query bar to search for logs by message, by field, or by a combination of both. -The query language is called [Kibana Query Language](../../../reference/observability/logs/kql.md) (`KQL`). KQL is a simplified version of Lucene query syntax. You can use KQL to search for logs by message, by field, or by a combination of both. +The query language is called [Kibana Query Language](../reference/kql.md) (`KQL`). KQL is a simplified version of Lucene query syntax. You can use KQL to search for logs by message, by field, or by a combination of both. There is also a time picker in the upper right corner of the page. You can use the time picker to select a time range to search for logs. The default time range is the last 15 minutes. If no logs shows up, try to increase the time range. diff --git a/tenants/nav/reference/observability/logs/kql.md b/tenants/nav/observability/logging/reference/kql.md similarity index 98% rename from tenants/nav/reference/observability/logs/kql.md rename to tenants/nav/observability/logging/reference/kql.md index e3f8a4c4..547b1780 100644 --- a/tenants/nav/reference/observability/logs/kql.md +++ b/tenants/nav/observability/logging/reference/kql.md @@ -1,7 +1,7 @@ --- title: KQL Reference description: Kibana Query Language (KQL) Reference for filtering data in Kibana. -tags: [reference, kibana] +tags: [reference, logging, kibana] --- # Kibana Query Language (KQL) Reference @@ -42,4 +42,4 @@ The following fields are common to all logs and can be used in your `KQL` query: | `message: "my message" OR level: "ERROR"` | Search for logs with the message "my message" or the level "ERROR" | | `message: "my message" AND NOT level: "ERROR"` | Search for logs with the message "my message" and not the level "ERROR" | | `message: "my message" AND level: "ERROR" AND NOT level: "WARN"` | Search for logs with the message "my message" and the level "ERROR" and not the level "WARN" | -| `message: "my message" AND level: "ERROR" OR level: "WARN"` | Search for logs with the message "my message" and the level "ERROR" or the level "WARN" | \ No newline at end of file +| `message: "my message" AND level: "ERROR" OR level: "WARN"` | Search for logs with the message "my message" and the level "ERROR" or the level "WARN" | diff --git a/tenants/nav/how-to-guides/observability/metrics/grafana-from-infoscreen.md b/tenants/nav/observability/metrics/how-to/grafana-from-infoscreen.md similarity index 98% rename from tenants/nav/how-to-guides/observability/metrics/grafana-from-infoscreen.md rename to tenants/nav/observability/metrics/how-to/grafana-from-infoscreen.md index 817a98cb..4f8b3833 100644 --- a/tenants/nav/how-to-guides/observability/metrics/grafana-from-infoscreen.md +++ b/tenants/nav/observability/metrics/how-to/grafana-from-infoscreen.md @@ -1,6 +1,6 @@ --- description: How to show Grafana on an info-screen -tags: [guide, grafana] +tags: [how-to, logging, grafana] --- # Show Grafana on info-screen diff --git a/tenants/nav/reference/cli/aiven.md b/tenants/nav/operate/cli/reference/aiven.md similarity index 88% rename from tenants/nav/reference/cli/aiven.md rename to tenants/nav/operate/cli/reference/aiven.md index 010f62a7..22b28565 100644 --- a/tenants/nav/reference/cli/aiven.md +++ b/tenants/nav/operate/cli/reference/aiven.md @@ -1,3 +1,7 @@ +--- +tags: [command-line, reference] +--- + # aiven command The aiven command can be used to create a AivenApplication and extract credentials. @@ -35,7 +39,7 @@ nais aiven create service username namespace ``` | Argument | Required | Description | -| --------- | -------- | ------------------------------------------------------------ | +|-----------|----------|--------------------------------------------------------------| | service | Yes | Service to use, Kafka or OpenSearch supported. | | username | Yes | Preferred username. | | namespace | Yes | Kubernetes namespace where AivenApplication will be created. | @@ -46,11 +50,11 @@ nais aiven create service username namespace nais aiven create -p nav-prod -s some-unique-secretname -e 10 kafka username namespace ``` -| Flag | Required | Short | Default | Description | -| ----------- | -------- | ----- | ------------------------------- | ------------------------------------------------ | -| pool | No | -p | nav-dev | [Kafka pool](../../persistence/kafka/README.md). | -| secret-name | No | -s | namespace-username-randomstring | Preferred secret-name. | -| expire | No | -e | 1 | Time in days the secret should be valid. | +| Flag | Required | Short | Default | Description | +|-------------|----------|-------|---------------------------------|-----------------------------------------------------| +| pool | No | -p | nav-dev | [Kafka pool](../../../persistence/kafka/README.md). | +| secret-name | No | -s | namespace-username-randomstring | Preferred secret-name. | +| expire | No | -e | 1 | Time in days the secret should be valid. | ### OpenSearch @@ -61,12 +65,12 @@ nais aiven create -i instance -a read -s some-unique-secretname -e 10 opensearch In OpenSearch, the username in the command is not related to the actual OpenSearch username, but used for internal purposes to identify the request. This is because the usernames on OpenSearch instances are pre-defined as of now, one for each possible access level. -| Flag | Required | Short | Default | Description | -| ----------- | -------- | ----- | ------------------------------- | ---------------------------------------------------------------------- | -| access | No | -a | read | One of: admin, read, write, readwrite. | -| instance | Yes | -i | | Name of the [instance](../../persistence/open-search.md#get-your-own). | -| secret-name | No | -s | namespace-username-randomstring | Preferred secret-name. | -| expire | No | -e | 1 | Time in days the secret should be valid. | +| Flag | Required | Short | Default | Description | +|-------------|----------|-------|---------------------------------|---------------------------------------------------------------------------| +| access | No | -a | read | One of: admin, read, write, readwrite. | +| instance | Yes | -i | | Name of the [instance](../../../persistence/opensearch/how-to/create.md). | +| secret-name | No | -s | namespace-username-randomstring | Preferred secret-name. | +| expire | No | -e | 1 | Time in days the secret should be valid. | ## get @@ -75,7 +79,7 @@ nais aiven get service secret-name namespace ``` | Argument | Required | Description | -| ----------- | -------- | ------------------------------------------------------ | +|-------------|----------|--------------------------------------------------------| | service | Yes | Service to use, Kafka or OpenSearch supported. | | secret-name | Yes | Default secret-name or flag `-s` in `create` command. | | namespace | Yes | Kubernetes namespace for the created AivenApplication. | diff --git a/tenants/nav/reference/cli/device.md b/tenants/nav/operate/cli/reference/device.md similarity index 87% rename from tenants/nav/reference/cli/device.md rename to tenants/nav/operate/cli/reference/device.md index 5dadcd66..39054cbe 100644 --- a/tenants/nav/reference/cli/device.md +++ b/tenants/nav/operate/cli/reference/device.md @@ -1,6 +1,10 @@ +--- +tags: [command-line, reference] +--- + # device command -The device command can be used to connect to, disconnect from, and view the connection status of [naisdevice](../../explanation/naisdevice.md). +The device command can be used to connect to, disconnect from, and view the connection status of [naisdevice](../../naisdevice/README.md). Currently, the command requires the processes `naisdevice-agent` and `naisdevice-helper` to run, both of which can be run by starting naisdevice. ## connect @@ -32,7 +36,7 @@ nais device status ``` | Flag | Required | Short | Default | Description | -| ------ | -------- | ----- | ------- | -------------------------------------------- | +|--------|----------|-------|---------|----------------------------------------------| | quiet | No | -q | false | Only print connection status. | | output | No | -o | yaml | Specify one of yaml or json as output format | @@ -50,7 +54,7 @@ nais device jita my-privileged-access-gateway ``` | Argument | Required | Description | -| -------- | -------- | ------------------------------------------------- | +|----------|----------|---------------------------------------------------| | gateway | Yes | The desired gateway to establish a connection to. | !!! tip "Which gateways require just-in-time access?" @@ -84,6 +88,6 @@ nais device config set AutoConnect true ``` | Argument | Required | Description | -| -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ | +|----------|----------|--------------------------------------------------------------------------------------------------------------------------------------| | setting | Yes | The setting to adjust. Must be one of `[autoconnect, certrenewal]`, case insensitive. | | value | Yes | The value to set. Must be one of `[true, false]`, or anything [`strconv.ParseBool`](https://pkg.go.dev/strconv#ParseBool) can parse. | diff --git a/tenants/nav/operate/naisdevice/.pages b/tenants/nav/operate/naisdevice/.pages new file mode 100644 index 00000000..33ee1c46 --- /dev/null +++ b/tenants/nav/operate/naisdevice/.pages @@ -0,0 +1,4 @@ +nav: + - πŸ’‘ Explanations: explanations + - 🎯 How-To: how-to + - ... diff --git a/tenants/nav/reference/naisdevice/jita.md b/tenants/nav/operate/naisdevice/explanations/jita.md similarity index 71% rename from tenants/nav/reference/naisdevice/jita.md rename to tenants/nav/operate/naisdevice/explanations/jita.md index 639fc0d2..82341354 100644 --- a/tenants/nav/reference/naisdevice/jita.md +++ b/tenants/nav/operate/naisdevice/explanations/jita.md @@ -1,3 +1,7 @@ +--- +tags: [naisdevice, jita, explanation] +--- + # Just In Time Access (JITA) ## Providing access to sensitive information @@ -7,10 +11,8 @@ When you start naisdevice you will not be automatically connected to all the ava !!! info The gateways currently requiring JITA are `aiven-prod`, `onprem-k8s-prod` and `postgres-prod`. - Access can be requested via the naisdevice menu or through the [nais cli](../cli/commands/device.md#jita). + Access can be requested via the naisdevice menu or through the [nais cli](../../cli/reference/device.md#jita). Once authenticated you will be presented with a form where you have to supply a short reason for why access is needed and for how long. You will then be granted access for the requested amount of time instantly and automatically. -![A screenshow shows the part of the form, where you supply the short reason for why access is needed and for how long. The label of the input field is "Reason". A slider below allows you to select the duraction.](../assets/jita_portal.png) - - +![A screenshot that shows the part of the form, where you supply the short reason for why access is needed and for how long. The label of the input field is "Reason". A slider below allows you to select the duraction.](../../../assets/jita_portal.png) diff --git a/tenants/nav/how-to-guides/naisdevice/install-kolide.md b/tenants/nav/operate/naisdevice/how-to/install-kolide.md similarity index 98% rename from tenants/nav/how-to-guides/naisdevice/install-kolide.md rename to tenants/nav/operate/naisdevice/how-to/install-kolide.md index 5342d765..7e45366a 100644 --- a/tenants/nav/how-to-guides/naisdevice/install-kolide.md +++ b/tenants/nav/operate/naisdevice/how-to/install-kolide.md @@ -1,3 +1,7 @@ +--- +tags: [naisdevice, how-to] +--- + # Install Kolide ### How to Install Kolide agent diff --git a/tenants/nav/how-to-guides/naisdevice/troubleshooting.md b/tenants/nav/operate/naisdevice/how-to/troubleshooting.md similarity index 93% rename from tenants/nav/how-to-guides/naisdevice/troubleshooting.md rename to tenants/nav/operate/naisdevice/how-to/troubleshooting.md index 2dc39e79..0fdec098 100644 --- a/tenants/nav/how-to-guides/naisdevice/troubleshooting.md +++ b/tenants/nav/operate/naisdevice/how-to/troubleshooting.md @@ -1,4 +1,8 @@ -# Troubleshooting +--- +tags: [naisdevice, how-to] +--- + +# Troubleshooting naisdevice - _naisdevice cannot connect, yet `/msg @Kolide status` is happy!_ - Disconnect and re-connect `naisdevice` =\)! diff --git a/tenants/nav/how-to-guides/naisdevice/uninstall-kolide.md b/tenants/nav/operate/naisdevice/how-to/uninstall-kolide.md similarity index 97% rename from tenants/nav/how-to-guides/naisdevice/uninstall-kolide.md rename to tenants/nav/operate/naisdevice/how-to/uninstall-kolide.md index 794fde77..30844d5c 100644 --- a/tenants/nav/how-to-guides/naisdevice/uninstall-kolide.md +++ b/tenants/nav/operate/naisdevice/how-to/uninstall-kolide.md @@ -1,3 +1,7 @@ +--- +tags: [naisdevice, how-to] +--- + # Uninstall Kolide === "macOS" diff --git a/tenants/nav/persistence/influxdb/.pages b/tenants/nav/persistence/influxdb/.pages new file mode 100644 index 00000000..f092fbf6 --- /dev/null +++ b/tenants/nav/persistence/influxdb/.pages @@ -0,0 +1,5 @@ +nav: +- README.md +- 🎯 How-To: how-to +- πŸ“š Reference: reference +- ... diff --git a/tenants/nav/persistence/influxdb/README.md b/tenants/nav/persistence/influxdb/README.md new file mode 100644 index 00000000..74ad9b23 --- /dev/null +++ b/tenants/nav/persistence/influxdb/README.md @@ -0,0 +1,53 @@ +--- +tags: [influxdb, persistence, explanation] +--- + +# InfluxDB + +During 2021 Aiven informed us that they would probably stop supporting InfluxDB at some point in the next couple years, but that no final decision was made. +For that reason, we discouraged use of Aiven InfluxDB and recommended that teams instead build a solution based around BigQuery for these kinds of business metrics. + +At the start of 2023, Aiven informed us that dropping InfluxDB was no longer in the roadmap, and that InfluxDB support would continue for the foreseeable future. +However, Aiven is still only supporting InfluxDB 1.8, and they have no plans to allow upgrading to InfluxDB 2 because of licensing issues. + +For that reason, we still discourage use of Aiven InfluxDB for new use cases. +For many use cases, the BigQuery alternative might be a better fit. + +See the end of this document for a description of [the BigQuery alternative](#suggested-alternative). + +## Getting started + +As there are few teams that need an InfluxDB instance we use a IaC-repo to provision each instance. +Head over to [aiven-iac](https://github.com/navikt/aiven-iac#influxdb) to learn how to get your own instance. + +## Usage + +:dart: [Access InfluxDB from an application](how-to/access.md) + +## Support + +We do not offer support on Influxdb as software, but questions about Aiven and provisioning can be directed to [#nais](https://nav-it.slack.com/archives/C5KUST8N6) on Slack. + +## Suggested alternative + +Team Digihot has spent some time piloting a concept that uses BigQuery and Metabase as a replacement for InfluxDB and Grafana. +They are very satisfied with the solution, and we have concluded that this is a viable replacement going forward. +In their case, all applications that sent data to InfluxDB also used Kafka, so their solution is based around Kafka. +Depending on the situation and use case, it would also be possible to send data to BigQuery directly from the applications. + +Once the data is in BigQuery, you can use Metabase to create dashboards or dataproducts. + +```mermaid +graph LR + accTitle: From Kafka to Metabase via BigQuery + accDescr: The diagram shows how the data is sent from the producer to Metabase. Producers on a kafka client, uses a kafka rapid, sending it to BigQuery sink ruler (BigQuery client) and BigQuery, that can be read from Metabase. Non-kafka apps can send data directly to BigQuery. + + P1[Producer 1
Kafka Client] --> K + P2[Producer 2
Kafka Client] --> K + + K[Kafka Rapid] --> BQSR + BQSR[BigQuery sink river
BigQuery Client] --> BQ + E[Non-Kafka App
BigQuery Client] --> BQ + + BQ[BigQuery] --> M[Metabase] +``` diff --git a/tenants/nav/how-to-guides/persistence/influxdb/access.md b/tenants/nav/persistence/influxdb/how-to/access.md similarity index 83% rename from tenants/nav/how-to-guides/persistence/influxdb/access.md rename to tenants/nav/persistence/influxdb/how-to/access.md index 53faf4ad..73dce25f 100644 --- a/tenants/nav/how-to-guides/persistence/influxdb/access.md +++ b/tenants/nav/persistence/influxdb/how-to/access.md @@ -1,7 +1,10 @@ +--- +tags: [influxdb, how-to] +--- # Access from NAIS-app -You need to specify the InfluxDB instance to get access from an application. See [nais.yaml-reference](/reference/application-spec#influxinstance). +You need to specify the InfluxDB instance to get access from an application. See [nais.yaml-reference](../../../workloads/application/reference/application-spec.md#influxinstance). When an application requesting an InfluxDB instance is deployed, credentials will be provided as environment variables. There is only one user for Influxdb, with complete access. diff --git a/tenants/nav/how-to-guides/persistence/influxdb/create.md b/tenants/nav/persistence/influxdb/how-to/create.md similarity index 62% rename from tenants/nav/how-to-guides/persistence/influxdb/create.md rename to tenants/nav/persistence/influxdb/how-to/create.md index 92c3e9a5..e4feca00 100644 --- a/tenants/nav/how-to-guides/persistence/influxdb/create.md +++ b/tenants/nav/persistence/influxdb/how-to/create.md @@ -1,10 +1,15 @@ +--- +tags: [influxdb, how-to] +--- + !!! info "Disclaimer" - We [discourage use of Aiven InfluxDB](/explanation/database/influxdb) for new use cases and don't support InfluxDB as software. [BigQuery ](/explanation/database/bigquery) might be a better fit for many use cases. Questions about Aiven and provisioning can be directed to #nais on Slack. + + We discourage use of Aiven InfluxDB](README.md) for new use cases and don't support InfluxDB as software. [BigQuery](../../bigquery/README.md) might be a better fit for many use cases. Questions about Aiven and provisioning can be directed to #nais on Slack. # 1. Get an InfluxDB instance We use a IaC-repo to provision InfluxDB instances. Head over to [aiven-iac](https://github.com/navikt/aiven-iac#influxdb) to learn how to get your own instance. -(TODO: NAV ONLY) + # 2. Retention policies The default database is created with a default retention policy of 30 days. You might want to adjust this by e.g. creating a new default retention policy with 1 year retention: diff --git a/tenants/nav/persistence/influxdb/reference.md b/tenants/nav/persistence/influxdb/reference.md new file mode 100644 index 00000000..86b6777d --- /dev/null +++ b/tenants/nav/persistence/influxdb/reference.md @@ -0,0 +1,28 @@ +--- +tags: [influxdb, reference] +--- + +# InfluxDB reference + +## Retention policies +The default database is created with a default retention policy of 30 days. You might want to adjust this by e.g. creating a new default retention policy with 1 year retention: + +``` +create retention policy "365d" on "defaultdb" duration 365d replication 1 shard duration 1w default +``` + +## Datasource in Grafana + +Let us know in [#nais](https://nav-it.slack.com/archives/C5KUST8N6) if you want your InfluxDB to be exposed in Grafana. +This means that everyone can access your data. + +## Access from laptop + +With Naisdevice you have access to the _aiven-prod_ gateway. +This is a JITA (just in time access) gateway, so you need to describe why, but the access is automatically given. + +``` +influx -username avnadmin -password foo -host influx-instancename-nav-dev.aivencloud.com -port 26482 -ssl +``` + +PS: Remember to use Influxdb CLI pre v2. For example v1.8.3. diff --git a/tenants/nav/how-to-guides/persistence/kafka/access-from-non-nais.md b/tenants/nav/persistence/kafka/how-to/access-from-non-nais.md similarity index 80% rename from tenants/nav/how-to-guides/persistence/kafka/access-from-non-nais.md rename to tenants/nav/persistence/kafka/how-to/access-from-non-nais.md index 7419cbc1..1aa9f0d3 100644 --- a/tenants/nav/how-to-guides/persistence/kafka/access-from-non-nais.md +++ b/tenants/nav/persistence/kafka/how-to/access-from-non-nais.md @@ -1,8 +1,12 @@ +--- +tags: [kafka, how-to] +--- + # Accessing topics from an application outside NAIS This guide will show you how to access a [Kafka topic](create.md) from an application outside NAIS clusters. -## 1. Enable access to the relevant pool in your [manifest](../../nais-application/application.md) +## Enable access to the relevant pool in your manifest ???+ note ".nais/aivenapp.yaml" @@ -22,21 +26,21 @@ This guide will show you how to access a [Kafka topic](create.md) from an applic !!! info The secretName must be a valid [DNS label](https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#dns-label-names), and must be unique within the namespace. -## 2. Apply the AivenApplication +## Apply the AivenApplication === "Automatically" - Add the file to your application repository, alongside `nais.yaml` to deploy with [NAIS github action](../../cicd/github-action.md). + Add the file to your application repository, alongside `nais.yaml` to deploy with [NAIS github action](../../../build/how-to/build-and-deploy.md). === "Manually" ```bash kubectl apply -f ./nais/aivenapp.yaml --namespace= --context= ``` -## 3. Extract the value of the generated secret +## Extract the value of the generated secret ```bash kubectl get secret --namespace --contect -o jsonpath='{.data}' ``` Make the values available to your application. -## 4. Grant access to the topic +## Grant access to the topic The owner of the topic must [grant your application access to the topic](manage-acl.md). diff --git a/tenants/nav/how-to-guides/persistence/kafka/renew-credentials-for-non-nais.md b/tenants/nav/persistence/kafka/how-to/renew-credentials-for-non-nais.md similarity index 90% rename from tenants/nav/how-to-guides/persistence/kafka/renew-credentials-for-non-nais.md rename to tenants/nav/persistence/kafka/how-to/renew-credentials-for-non-nais.md index 0667eedd..8a7ddd63 100644 --- a/tenants/nav/how-to-guides/persistence/kafka/renew-credentials-for-non-nais.md +++ b/tenants/nav/persistence/kafka/how-to/renew-credentials-for-non-nais.md @@ -1,3 +1,7 @@ +--- +tags: [kafka, how-to] +--- + # Renew credentials for non-NAIS applications Eventually the credentials created in [Accessing topics from an application outside NAIS](access-from-non-nais.md) will expire. @@ -5,18 +9,18 @@ Well in advance of this, Aiven will issue a notification to the technical contac When it is time to renew the credentials, follow these steps: -## 1. Edit the AivenApplication resource +## Edit the AivenApplication resource You need to change the `.spec.secretName` field in the `AivenApplication` resource you used to create the credentials in the first place. Make a note of the current value, and change it to something suitable. You can use any valid name you want, but make sure it is different from the old name. -## 2. Wait for a new secret to appear +## Wait for a new secret to appear When you save/apply the changed secret name, new credentials are generated. When complete, a secret with the requested name will become available in the cluster. -## 3. Extract updated credentials +## Extract updated credentials Extract the credentials from the newly created secret, in the same way as you originally did when you first created the `AivenApplication` resource. @@ -26,7 +30,7 @@ kubectl get secret --namespace --contect .dev-fss-pub.nais.io` + - `https://.prod-fss-pub.nais.io` + + The application _on-premises_ must then: + + 1. Add the ingress created above to the list of ingresses: + + ```yaml + spec: + ingresses: + - https://.-fss-pub.nais.io + ``` + + 2. If secured with OAuth 2.0, ensure that the application also has set up inbound access policies: + - a. [Access Policies for TokenX][tokenx-access] + - b. [Access Policies for Azure AD)][azure-ad-access] + +The application _in GCP_ must then: + +1. Add the above hosts to their [outbound external access policies][access-policies]: + + ```yaml + spec: + accessPolicy: + outbound: + external: + - host: .-fss-pub.nais.io + ``` + +### How do I reach an application found on GCP from my application on-premises? + +???+ faq "Answer" + + The application in GCP must be exposed on a [matching ingress][environments]: + + | ingress | reachable from zone | + | :--- | :--- | + | `.intern.dev.nav.no` | `dev-fss` | + | `.intern.nav.no` | `prod-fss` | + | `.nav.no` | internet, i.e. all clusters | + + The application on-premises should _not_ have to use webproxy to reach these ingresses. + +## GCP compared to on-premises + +| Feature | on-prem | gcp | Comment | +|:--------------------------|:-----------|:-------------------|:----------------------------------------------------------------| +| Deploy | yes | yes | different clustername when deploying | +| Logging | yes | yes | different clustername in logs.adeo.no | +| Metrics | yes | yes | same mechanism, different datasource | +| Nais app dashboard | yes | yes | new and improved in GCP | +| Alerts | yes | yes | identical | +| Secure logs | yes | yes | different clustername in logs.adeo.no | +| Kafka | yes | yes | identical | +| Secrets | Vault | Console secrets | | +| Team namespaces | yes | yes | | +| Shared namespaces | yes | no | Default namespace not available for teams in GCP | +| Health checks | yes | yes | identical | +| Ingress | yes | yes | See [environments overview][environments] for available domains | +| Storage | Ceph | Buckets | | +| Postgres | yes (IAC) | yes (self-service) | | +| Laptop access | yes | yes | | +| domain: dev.intern.nav.no | | yes (Automatic) | Wildcard DNS points to GCP load balancer | +| Access to FSS services | | yes | Identical (either API-gw or TokenX) | +| NAV truststore | yes | yes | | +| PVK required | yes | yes | amend to cover storage in cloud | +| Security | Zone Model | [zero-trust] | | + +[zero-trust]: zero-trust.md +[nais-yaml]: ../../workloads/application/reference/application-example.md +[buckets]: ../../persistence/buckets/README.md +[postgres]: ../../persistence/postgres/README.md +[migrate-database]: ../../persistence/postgres/how-to/migrating-databases-to-gcp.md +[environments]: ../reference/environments.md +[secrets]: ../../services/secrets/README.md +[auth]: ../../security/auth/README.md +[tokenx]: ../../security/auth/tokenx.md#access-policies +[tokenx-access]: ../../security/auth/tokenx.md +[azure-ad]: ../../security/auth/azure-ad/README.md +[azure-ad-access]: ../../security/auth/azure-ad/configuration.md#pre-authorization +[access-policies]: ../how-to/access-policies.md +[roles-responsibilites]: ../../legal/roles-responsibilities.md +[pvk]: ../../legal/app-pvk.md +[ros]: ../../legal/nais-ros.md diff --git a/tenants/ssb/reference/environments.md b/tenants/ssb/reference/environments.md deleted file mode 100644 index 5521d6f1..00000000 --- a/tenants/ssb/reference/environments.md +++ /dev/null @@ -1,31 +0,0 @@ -# Available environments - -This is a overview over the different environments and available domains. - -We also enumerate the external IPs used by the environments, so that you can provide them to services that require IP allow-listing. - -### staging - -#### Domains - -| domain | accessible from | description | -| :--- | :--- | :--- | -| external.staging.ssb.cloud.nais.io | Internet | ingress for applications exposed to Internet. URLs containing `/metrics`, `/actuator` or `/internal` are blocked. | -| staging.ssb.cloud.nais.io | [naisdevice](../explanation/naisdevice.md) | ingress for internal applications | - -#### External/outbound IPs - -- 34.88.116.202 - -### prod - -#### Domains - -| domain | accessible from | description | -| :--- | :--- | :--- | -| external.prod.ssb.cloud.nais.io | Internet | ingress for applications exposed to Internet. URLs containing `/metrics`, `/actuator` or `/internal` are blocked. | -| prod.ssb.cloud.nais.io | [naisdevice](../explanation/naisdevice.md) | ingress for internal applications | - -#### External/outbound IPs - -- 34.88.47.40