From 1d6fa179b731c2e824fe38db6cc9812b8e6297a1 Mon Sep 17 00:00:00 2001 From: Murad Biashimov Date: Wed, 3 Jul 2024 13:17:43 +0200 Subject: [PATCH] docs: add secret dependency warning (#779) --- docs/docs/api-reference/cassandra.md | 3 ++ docs/docs/api-reference/clickhouse.md | 3 ++ docs/docs/api-reference/clickhousedatabase.md | 3 ++ docs/docs/api-reference/clickhousegrant.md | 3 ++ docs/docs/api-reference/clickhouserole.md | 3 ++ docs/docs/api-reference/clickhouseuser.md | 3 ++ docs/docs/api-reference/connectionpool.md | 3 ++ docs/docs/api-reference/database.md | 3 ++ docs/docs/api-reference/grafana.md | 3 ++ docs/docs/api-reference/kafka.md | 3 ++ docs/docs/api-reference/kafkaacl.md | 3 ++ docs/docs/api-reference/kafkaconnect.md | 3 ++ docs/docs/api-reference/kafkaschema.md | 3 ++ .../api-reference/kafkaschemaregistryacl.md | 3 ++ docs/docs/api-reference/kafkatopic.md | 3 ++ docs/docs/api-reference/mysql.md | 3 ++ docs/docs/api-reference/opensearch.md | 3 ++ docs/docs/api-reference/postgresql.md | 3 ++ docs/docs/api-reference/project.md | 3 ++ docs/docs/api-reference/projectvpc.md | 3 ++ docs/docs/api-reference/redis.md | 3 ++ docs/docs/api-reference/serviceintegration.md | 3 ++ .../serviceintegrationendpoint.md | 3 ++ docs/docs/api-reference/serviceuser.md | 3 ++ docs/docs/authentication.md | 9 ++-- generators/docs/generator.go | 45 +++++++++++-------- 26 files changed, 103 insertions(+), 23 deletions(-) diff --git a/docs/docs/api-reference/cassandra.md b/docs/docs/api-reference/cassandra.md index 90c281a5..43997101 100644 --- a/docs/docs/api-reference/cassandra.md +++ b/docs/docs/api-reference/cassandra.md @@ -40,6 +40,9 @@ title: "Cassandra" - network: 10.20.0.0/16 ``` +!!! info + To create this resource, a `Secret` containing Aiven token must be [created](/aiven-operator/authentication.html) first. + Apply the resource with: ```shell diff --git a/docs/docs/api-reference/clickhouse.md b/docs/docs/api-reference/clickhouse.md index b15a9358..ac28f0e2 100644 --- a/docs/docs/api-reference/clickhouse.md +++ b/docs/docs/api-reference/clickhouse.md @@ -40,6 +40,9 @@ title: "Clickhouse" maintenanceWindowTime: 23:00:00 ``` +!!! info + To create this resource, a `Secret` containing Aiven token must be [created](/aiven-operator/authentication.html) first. + Apply the resource with: ```shell diff --git a/docs/docs/api-reference/clickhousedatabase.md b/docs/docs/api-reference/clickhousedatabase.md index 81972d47..a1f9771d 100644 --- a/docs/docs/api-reference/clickhousedatabase.md +++ b/docs/docs/api-reference/clickhousedatabase.md @@ -20,6 +20,9 @@ title: "ClickhouseDatabase" databaseName: example-db ``` +!!! info + To create this resource, a `Secret` containing Aiven token must be [created](/aiven-operator/authentication.html) first. + Apply the resource with: ```shell diff --git a/docs/docs/api-reference/clickhousegrant.md b/docs/docs/api-reference/clickhousegrant.md index 08c6ca10..8203a309 100644 --- a/docs/docs/api-reference/clickhousegrant.md +++ b/docs/docs/api-reference/clickhousegrant.md @@ -46,6 +46,9 @@ title: "ClickhouseGrant" - role: my-role ``` +!!! info + To create this resource, a `Secret` containing Aiven token must be [created](/aiven-operator/authentication.html) first. + Apply the resource with: ```shell diff --git a/docs/docs/api-reference/clickhouserole.md b/docs/docs/api-reference/clickhouserole.md index 55e5f098..cd2f344b 100644 --- a/docs/docs/api-reference/clickhouserole.md +++ b/docs/docs/api-reference/clickhouserole.md @@ -20,6 +20,9 @@ title: "ClickhouseRole" role: my-role ``` +!!! info + To create this resource, a `Secret` containing Aiven token must be [created](/aiven-operator/authentication.html) first. + Apply the resource with: ```shell diff --git a/docs/docs/api-reference/clickhouseuser.md b/docs/docs/api-reference/clickhouseuser.md index 14e3abe2..6418ada0 100644 --- a/docs/docs/api-reference/clickhouseuser.md +++ b/docs/docs/api-reference/clickhouseuser.md @@ -42,6 +42,9 @@ title: "ClickhouseUser" plan: startup-16 ``` +!!! info + To create this resource, a `Secret` containing Aiven token must be [created](/aiven-operator/authentication.html) first. + Apply the resource with: ```shell diff --git a/docs/docs/api-reference/connectionpool.md b/docs/docs/api-reference/connectionpool.md index f424b025..a5296b55 100644 --- a/docs/docs/api-reference/connectionpool.md +++ b/docs/docs/api-reference/connectionpool.md @@ -66,6 +66,9 @@ title: "ConnectionPool" serviceName: my-pg ``` +!!! info + To create this resource, a `Secret` containing Aiven token must be [created](/aiven-operator/authentication.html) first. + Apply the resource with: ```shell diff --git a/docs/docs/api-reference/database.md b/docs/docs/api-reference/database.md index ab234051..0fe5e21a 100644 --- a/docs/docs/api-reference/database.md +++ b/docs/docs/api-reference/database.md @@ -22,6 +22,9 @@ title: "Database" lcCollate: en_US.UTF-8 ``` +!!! info + To create this resource, a `Secret` containing Aiven token must be [created](/aiven-operator/authentication.html) first. + Apply the resource with: ```shell diff --git a/docs/docs/api-reference/grafana.md b/docs/docs/api-reference/grafana.md index 543c44dc..7ffd747b 100644 --- a/docs/docs/api-reference/grafana.md +++ b/docs/docs/api-reference/grafana.md @@ -39,6 +39,9 @@ title: "Grafana" - network: 10.20.0.0/16 ``` +!!! info + To create this resource, a `Secret` containing Aiven token must be [created](/aiven-operator/authentication.html) first. + Apply the resource with: ```shell diff --git a/docs/docs/api-reference/kafka.md b/docs/docs/api-reference/kafka.md index 42e04782..69604aab 100644 --- a/docs/docs/api-reference/kafka.md +++ b/docs/docs/api-reference/kafka.md @@ -31,6 +31,9 @@ title: "Kafka" maintenanceWindowTime: 23:00:00 ``` +!!! info + To create this resource, a `Secret` containing Aiven token must be [created](/aiven-operator/authentication.html) first. + Apply the resource with: ```shell diff --git a/docs/docs/api-reference/kafkaacl.md b/docs/docs/api-reference/kafkaacl.md index efb695e8..f197dc73 100644 --- a/docs/docs/api-reference/kafkaacl.md +++ b/docs/docs/api-reference/kafkaacl.md @@ -22,6 +22,9 @@ title: "KafkaACL" permission: admin ``` +!!! info + To create this resource, a `Secret` containing Aiven token must be [created](/aiven-operator/authentication.html) first. + Apply the resource with: ```shell diff --git a/docs/docs/api-reference/kafkaconnect.md b/docs/docs/api-reference/kafkaconnect.md index 8a3cc3e3..7f4f14f7 100644 --- a/docs/docs/api-reference/kafkaconnect.md +++ b/docs/docs/api-reference/kafkaconnect.md @@ -26,6 +26,9 @@ title: "KafkaConnect" kafka_connect: true ``` +!!! info + To create this resource, a `Secret` containing Aiven token must be [created](/aiven-operator/authentication.html) first. + Apply the resource with: ```shell diff --git a/docs/docs/api-reference/kafkaschema.md b/docs/docs/api-reference/kafkaschema.md index a44d9a43..f2ac1a57 100644 --- a/docs/docs/api-reference/kafkaschema.md +++ b/docs/docs/api-reference/kafkaschema.md @@ -35,6 +35,9 @@ title: "KafkaSchema" } ``` +!!! info + To create this resource, a `Secret` containing Aiven token must be [created](/aiven-operator/authentication.html) first. + Apply the resource with: ```shell diff --git a/docs/docs/api-reference/kafkaschemaregistryacl.md b/docs/docs/api-reference/kafkaschemaregistryacl.md index 58576915..8e56b1bc 100644 --- a/docs/docs/api-reference/kafkaschemaregistryacl.md +++ b/docs/docs/api-reference/kafkaschemaregistryacl.md @@ -22,6 +22,9 @@ title: "KafkaSchemaRegistryACL" permission: schema_registry_read ``` +!!! info + To create this resource, a `Secret` containing Aiven token must be [created](/aiven-operator/authentication.html) first. + Apply the resource with: ```shell diff --git a/docs/docs/api-reference/kafkatopic.md b/docs/docs/api-reference/kafkatopic.md index 28bd8b0c..fe7fb6f2 100644 --- a/docs/docs/api-reference/kafkatopic.md +++ b/docs/docs/api-reference/kafkatopic.md @@ -26,6 +26,9 @@ title: "KafkaTopic" min_cleanable_dirty_ratio: 0.2 ``` +!!! info + To create this resource, a `Secret` containing Aiven token must be [created](/aiven-operator/authentication.html) first. + Apply the resource with: ```shell diff --git a/docs/docs/api-reference/mysql.md b/docs/docs/api-reference/mysql.md index a43e1481..f05b8b21 100644 --- a/docs/docs/api-reference/mysql.md +++ b/docs/docs/api-reference/mysql.md @@ -39,6 +39,9 @@ title: "MySQL" - network: 10.20.0.0/16 ``` +!!! info + To create this resource, a `Secret` containing Aiven token must be [created](/aiven-operator/authentication.html) first. + Apply the resource with: ```shell diff --git a/docs/docs/api-reference/opensearch.md b/docs/docs/api-reference/opensearch.md index d19f15e2..07f01739 100644 --- a/docs/docs/api-reference/opensearch.md +++ b/docs/docs/api-reference/opensearch.md @@ -32,6 +32,9 @@ title: "OpenSearch" maintenanceWindowTime: 23:00:00 ``` +!!! info + To create this resource, a `Secret` containing Aiven token must be [created](/aiven-operator/authentication.html) first. + Apply the resource with: ```shell diff --git a/docs/docs/api-reference/postgresql.md b/docs/docs/api-reference/postgresql.md index 6e42b5f5..bf808aec 100644 --- a/docs/docs/api-reference/postgresql.md +++ b/docs/docs/api-reference/postgresql.md @@ -34,6 +34,9 @@ title: "PostgreSQL" pg_version: "15" ``` +!!! info + To create this resource, a `Secret` containing Aiven token must be [created](/aiven-operator/authentication.html) first. + Apply the resource with: ```shell diff --git a/docs/docs/api-reference/project.md b/docs/docs/api-reference/project.md index e8f2ec01..72fb2980 100644 --- a/docs/docs/api-reference/project.md +++ b/docs/docs/api-reference/project.md @@ -30,6 +30,9 @@ title: "Project" cloud: aws-eu-west-1 ``` +!!! info + To create this resource, a `Secret` containing Aiven token must be [created](/aiven-operator/authentication.html) first. + Apply the resource with: ```shell diff --git a/docs/docs/api-reference/projectvpc.md b/docs/docs/api-reference/projectvpc.md index 97848efd..705577da 100644 --- a/docs/docs/api-reference/projectvpc.md +++ b/docs/docs/api-reference/projectvpc.md @@ -20,6 +20,9 @@ title: "ProjectVPC" networkCidr: 10.0.0.0/24 ``` +!!! info + To create this resource, a `Secret` containing Aiven token must be [created](/aiven-operator/authentication.html) first. + Apply the resource with: ```shell diff --git a/docs/docs/api-reference/redis.md b/docs/docs/api-reference/redis.md index ab6618ca..b5870dcf 100644 --- a/docs/docs/api-reference/redis.md +++ b/docs/docs/api-reference/redis.md @@ -34,6 +34,9 @@ title: "Redis" redis_maxmemory_policy: allkeys-random ``` +!!! info + To create this resource, a `Secret` containing Aiven token must be [created](/aiven-operator/authentication.html) first. + Apply the resource with: ```shell diff --git a/docs/docs/api-reference/serviceintegration.md b/docs/docs/api-reference/serviceintegration.md index 2a90cb85..0877ed55 100644 --- a/docs/docs/api-reference/serviceintegration.md +++ b/docs/docs/api-reference/serviceintegration.md @@ -208,6 +208,9 @@ title: "ServiceIntegration" partitions: 1 ``` +!!! info + To create this resource, a `Secret` containing Aiven token must be [created](/aiven-operator/authentication.html) first. + Apply the resource with: ```shell diff --git a/docs/docs/api-reference/serviceintegrationendpoint.md b/docs/docs/api-reference/serviceintegrationendpoint.md index cb40ca17..60d4e930 100644 --- a/docs/docs/api-reference/serviceintegrationendpoint.md +++ b/docs/docs/api-reference/serviceintegrationendpoint.md @@ -49,6 +49,9 @@ title: "ServiceIntegrationEndpoint" basic_auth_password: password ``` +!!! info + To create this resource, a `Secret` containing Aiven token must be [created](/aiven-operator/authentication.html) first. + Apply the resource with: ```shell diff --git a/docs/docs/api-reference/serviceuser.md b/docs/docs/api-reference/serviceuser.md index 77caa0d6..19c13b0d 100644 --- a/docs/docs/api-reference/serviceuser.md +++ b/docs/docs/api-reference/serviceuser.md @@ -27,6 +27,9 @@ title: "ServiceUser" serviceName: my-service-name ``` +!!! info + To create this resource, a `Secret` containing Aiven token must be [created](/aiven-operator/authentication.html) first. + Apply the resource with: ```shell diff --git a/docs/docs/authentication.md b/docs/docs/authentication.md index d31ebe1b..cc20afa7 100644 --- a/docs/docs/authentication.md +++ b/docs/docs/authentication.md @@ -5,12 +5,13 @@ weight: 10 --- To get authenticated and authorized, set up the communication between the Aiven Operator for Kubernetes and Aiven by -using a token stored in a Kubernetes Secret. You can then refer to the Secret name on every custom resource in +using a token stored in a Kubernetes Secret. You can then refer to the `Secret` name on every custom resource in the `authSecretRef` field. -**If you don't have an Aiven account yet, sign -up [here](https://console.aiven.io/signup?utm_source=github&utm_medium=organic&utm_campaign=k8s-operator&utm_content=signup) -for a free trial. 🦀** +!!! important + If you don't have an Aiven account yet, sign + up [here](https://console.aiven.io/signup?utm_source=github&utm_medium=organic&utm_campaign=k8s-operator&utm_content=signup) + for a free trial 🦀 1\. Generate an authentication token diff --git a/generators/docs/generator.go b/generators/docs/generator.go index d5f7901f..627dd556 100644 --- a/generators/docs/generator.go +++ b/generators/docs/generator.go @@ -421,9 +421,12 @@ var templateFuncs = template.FuncMap{ "indent": func(i int, src string) string { return reIndent.ReplaceAllString(src, strings.Repeat(" ", i)) }, - "backtick": func(i int) string { + "code": func(s string) string { + return fmt.Sprintf("`%s`", s) + }, + "codeblock": func() string { // we can't use backticks in go strings, so we render them - return strings.Repeat("`", i) + return "```" }, "rfill": rfill, } @@ -437,51 +440,55 @@ title: "{{ .Kind }}" {{ range .UsageExamples }} ??? example {{ if .Title }}"{{ .Title }}"{{ end }} - {{ backtick 3 }}yaml + {{ codeblock }}yaml {{ .Value | indent 4 }} - {{ backtick 3 }} + {{ codeblock }} {{ end }} {{ $example := .GetExample }} {{ if $example }} + +!!! info + To create this resource, a {{ code "Secret" }} containing Aiven token must be [created](/aiven-operator/authentication.html) first. + Apply the resource with: -{{ backtick 3 }}shell +{{ codeblock }}shell kubectl apply -f example.yaml -{{ backtick 3 }} +{{ codeblock }} -Verify the newly created {{ backtick 1 }}{{ .Kind }}{{ backtick 1 }}: +Verify the newly created {{ code .Kind }}: -{{ backtick 3 }}shell +{{ codeblock }}shell kubectl get {{ .Plural }} {{ $example.Metadata.Name }} -{{ backtick 3 }} +{{ codeblock }} The output is similar to the following: -{{ backtick 3 }}shell +{{ codeblock }}shell {{ range $example.Table }}{{ rfill .Title .Value }} {{ end }} {{ range $example.Table }}{{ rfill .Value .Title }} {{ end }} -{{ backtick 3 }} +{{ codeblock }} {{ if $example.Secret.Name }} -To view the details of the {{ backtick 1 }}Secret{{ backtick 1 }}, use the following command: -{{ backtick 3 }}shell +To view the details of the {{ code "Secret" }}, use the following command: +{{ codeblock }}shell kubectl describe secret {{ $example.Secret.Name }} -{{ backtick 3 }} +{{ codeblock }} -You can use the [jq](https://github.com/jqlang/jq) to quickly decode the {{ backtick 1 }}Secret{{ backtick 1 }}: +You can use the [jq](https://github.com/jqlang/jq) to quickly decode the {{ code "Secret" }}: -{{ backtick 3 }}shell +{{ codeblock }}shell kubectl get secret {{ $example.Secret.Name }} -o json | jq '.data | map_values(@base64d)' -{{ backtick 3 }} +{{ codeblock }} The output is similar to the following: -{{ backtick 3 }}{ .json .no-copy } +{{ codeblock }}{ .json .no-copy } { {{- range $example.Secret.Keys }} "{{ . }}": "",{{ end }} } -{{ backtick 3 }} +{{ codeblock }} {{ end }}