diff --git a/.github/scripts/generate-crd-docs/generate-crd-docs.sh b/.github/scripts/generate-crd-docs/generate-crd-docs.sh index cc2fb02f73..6effbb2217 100755 --- a/.github/scripts/generate-crd-docs/generate-crd-docs.sh +++ b/.github/scripts/generate-crd-docs/generate-crd-docs.sh @@ -1,6 +1,6 @@ #!/bin/bash -# CRD docs auto generation script +# API docs auto generation script # # This script goes through all API definitions in the operator/apis folder # and generates docs from code for each API group and version @@ -23,11 +23,11 @@ else echo "Docs generator is installed, continuing..." fi -echo "Running CRD docs auto-generator..." +echo "Running API docs auto-generator..." for api_group in "$API_ROOT"*; do sanitized_api_group="${api_group#$API_ROOT}" - INDEX_PATH="./docs/content/en/docs/crd-ref/$sanitized_api_group/_index.md" + INDEX_PATH="./docs/content/en/docs/api-ref/$sanitized_api_group/_index.md" if [ ! -f "$INDEX_PATH" ]; then echo "API group index file doesn't exist for group $sanitized_api_group. Creating it now..." @@ -41,7 +41,7 @@ for api_group in "$API_ROOT"*; do for api_version in "$api_group"/*; do sanitized_api_version="${api_version#$API_ROOT$sanitized_api_group/}" - OUTPUT_PATH="./docs/content/en/docs/crd-ref/$sanitized_api_group/$sanitized_api_version" + OUTPUT_PATH="./docs/content/en/docs/api-ref/$sanitized_api_group/$sanitized_api_version" echo "Arguments:" echo "TEMPLATE_DIR: $TEMPLATE_DIR" @@ -55,7 +55,7 @@ for api_group in "$API_ROOT"*; do echo "Creating docs folder $OUTPUT_PATH..." mkdir -p "$OUTPUT_PATH" - echo "Generating CRD docs for $sanitized_api_group.$API_DOMAIN/$sanitized_api_version..." + echo "Generating API docs for $sanitized_api_group.$API_DOMAIN/$sanitized_api_version..." crd-ref-docs \ --templates-dir "$TEMPLATE_DIR" \ --source-path="./$api_version" \ diff --git a/.github/workflows/markdown-checks.yaml b/.github/workflows/markdown-checks.yaml index 39a0b22eca..c536e8e457 100644 --- a/.github/workflows/markdown-checks.yaml +++ b/.github/workflows/markdown-checks.yaml @@ -77,18 +77,18 @@ jobs: - name: Copy old docs run: | - cp -R ./docs/content/en/docs/crd-ref ./docs/content/en/docs/crd-ref-old + cp -R ./docs/content/en/docs/api-ref ./docs/content/en/docs/api-ref-old - name: Run docs generator run: ./.github/scripts/generate-crd-docs/generate-crd-docs.sh - name: Check if docs are up to date run: | - if ! diff -rq ./docs/content/en/docs/crd-ref ./docs/content/en/docs/crd-ref-old &>/dev/null; then + if ! diff -rq ./docs/content/en/docs/api-ref ./docs/content/en/docs/api-ref-old &>/dev/null; then echo "The CRD docs have changes that are not reflected in the docs pages. Please use ./.github/scripts/generate-crd-docs/generate-crd-docs.sh to re-generate the docs." echo "" echo "=========== Diff ===========" - diff -ru ./docs/content/en/docs/crd-ref ./docs/content/en/docs/crd-ref-old + diff -ru ./docs/content/en/docs/api-ref ./docs/content/en/docs/api-ref-old exit 1 else echo "" diff --git a/docs/.htmltest.yml b/docs/.htmltest.yml index 9f9ba77c85..a40d1e61fe 100644 --- a/docs/.htmltest.yml +++ b/docs/.htmltest.yml @@ -2,7 +2,7 @@ CheckDoctype: false IgnoreDirs: - favicons - - docs/crd-ref/lifecycle/ + - docs/api-ref/lifecycle/ IgnoreURLs: - "linkedin.com" - "localhost" diff --git a/docs/content/en/docs/api-ref/_index.md b/docs/content/en/docs/api-ref/_index.md new file mode 100644 index 0000000000..4bda1b6dd5 --- /dev/null +++ b/docs/content/en/docs/api-ref/_index.md @@ -0,0 +1,26 @@ +--- +title: API Reference +description: Reference information about the KLT CRDs +weight: 100 +hidechildren: false # this flag hides all sub-pages in the sidebar-multicard.html +--- + +This section provides comprehensive reference information about the +[Custom Resource Definitions (CRDs)](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) +that are defined for the Keptn Lifecycle Toolkit. + +> **Note** +This section is under development. +Information that is published here has been reviewed for technical accuracy +but the format and content is still evolving. +We welcome your input!** + +By introducing CRDs, Keptn is extending the base Kubernetes API with new objects and functionality. +Keptn APIs follow API versioning conventions recommended by Kubernetes and are themselves composed of objects and sub-objects. + +For more information, see the Kubernetes documentation: + +* [API Overview](https://kubernetes.io/docs/reference/using-api/) +* [Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) +* [API versioning](https://kubernetes.io/docs/reference/using-api/#api-versioning) +* [Understanding Kubernetes Objects](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/) diff --git a/docs/content/en/docs/api-ref/lifecycle/_index.md b/docs/content/en/docs/api-ref/lifecycle/_index.md new file mode 100644 index 0000000000..1086280488 --- /dev/null +++ b/docs/content/en/docs/api-ref/lifecycle/_index.md @@ -0,0 +1,4 @@ +--- +title: Lifecycle API +description: Reference information about the Lifecycle API group +--- diff --git a/docs/content/en/docs/crd-ref/lifecycle/v1alpha1/_index.md b/docs/content/en/docs/api-ref/lifecycle/v1alpha1/_index.md similarity index 100% rename from docs/content/en/docs/crd-ref/lifecycle/v1alpha1/_index.md rename to docs/content/en/docs/api-ref/lifecycle/v1alpha1/_index.md diff --git a/docs/content/en/docs/crd-ref/lifecycle/v1alpha2/_index.md b/docs/content/en/docs/api-ref/lifecycle/v1alpha2/_index.md similarity index 100% rename from docs/content/en/docs/crd-ref/lifecycle/v1alpha2/_index.md rename to docs/content/en/docs/api-ref/lifecycle/v1alpha2/_index.md diff --git a/docs/content/en/docs/crd-ref/lifecycle/v1alpha3/_index.md b/docs/content/en/docs/api-ref/lifecycle/v1alpha3/_index.md similarity index 100% rename from docs/content/en/docs/crd-ref/lifecycle/v1alpha3/_index.md rename to docs/content/en/docs/api-ref/lifecycle/v1alpha3/_index.md diff --git a/docs/content/en/docs/crd-ref/metrics/_index.md b/docs/content/en/docs/api-ref/metrics/_index.md similarity index 100% rename from docs/content/en/docs/crd-ref/metrics/_index.md rename to docs/content/en/docs/api-ref/metrics/_index.md diff --git a/docs/content/en/docs/crd-ref/metrics/v1alpha1/_index.md b/docs/content/en/docs/api-ref/metrics/v1alpha1/_index.md similarity index 100% rename from docs/content/en/docs/crd-ref/metrics/v1alpha1/_index.md rename to docs/content/en/docs/api-ref/metrics/v1alpha1/_index.md diff --git a/docs/content/en/docs/crd-ref/options/_index.md b/docs/content/en/docs/api-ref/options/_index.md similarity index 100% rename from docs/content/en/docs/crd-ref/options/_index.md rename to docs/content/en/docs/api-ref/options/_index.md diff --git a/docs/content/en/docs/crd-ref/options/v1alpha1/_index.md b/docs/content/en/docs/api-ref/options/v1alpha1/_index.md similarity index 100% rename from docs/content/en/docs/crd-ref/options/v1alpha1/_index.md rename to docs/content/en/docs/api-ref/options/v1alpha1/_index.md diff --git a/docs/content/en/docs/crd-ref/TaskDefinition/index.md b/docs/content/en/docs/crd-ref/TaskDefinition/index.md new file mode 100644 index 0000000000..d3a350e7f6 --- /dev/null +++ b/docs/content/en/docs/crd-ref/TaskDefinition/index.md @@ -0,0 +1,288 @@ +--- +title: KeptnTaskDefinition +description: Define tasks that can be run pre- or post-deployment +weight: 89 +--- + +A `KeptnTaskDefinition` defines tasks +that are run by the Keptn Lifecycle Toolkit +as part of the pre- and post-deployment phases of a `KeptnApp`. + +## Yaml Synopsis + +```yaml +apiVersion: <lifecycle.keptn.sh/v?alpha?> +kind: KeptnTaskDefinition +metadata: + name: <task-name> +spec: + function: + inline | httpRef | functionRef: + [parameters: + map: + textMessage: "This is my configuration"] + [secureParameters: + secret: slack-token] +``` + +## Fields + +* **apiVersion** -- API version being used. +` +* **kind** -- Resource type. Must be set to `KeptnTaskDefinition` + +* **name** -- Unique name of this task. + * Must be an alphanumeric string and, by convention, is all lowercase. + * Can include the special characters `_`, `-`, <what others>. + * Should not include spaces. + +* **function** -- Code to be executed, + expressed as a [Deno](https://deno.land/) script. + Refer to [function runtime](https://github.com/keptn/lifecycle-toolkit/tree/main/functions-runtime) + for more information about the runtime. + + The `function` can be defined as one of the following: + + * **inline** - Include the actual executable code to execute. + This can be written as a full-fledged Deno script + that is included in this file. + For example: + + ```yaml + function: + inline: + code: | + console.log("Deployment Task has been executed"); + ``` + + * **httpRef** - Specify a Deno script to be executed at runtime + from the remote webserver that is specified. + For example: + + ```yaml + name: hello-keptn-http + spec: + function: + httpRef: + url: "https://www.example.com/yourscript.js" + ``` + + * **functionRef** -- Execute another `KeptnTaskDefinition` that has been defined. + Populate this field with the value of the `name` field + for the `KeptnTaskDefinition` to be called. + This is commonly used to call a general function + that is used in multiple places, possibly with different parameters. + An example is: + + ```yaml + spec: + function: + functionRef: + name: slack-notification + ``` + + This can also be used to group a set of tasks + into a single `KeptnTaskDefinition`, + such as defining a `KeptnTaskDefinition` for testing. + In this case, it other, existing `KeptnTaskDefinition`s + for each type of test to be run, + specifying each by the value of the `name` field. + +* **parameters** - An optional field to supply input parameters to a function. + The Lifecycle Toolkit passes the values defined inside the `map` field + as a JSON object. + For example: + + ```yaml + spec: + parameters: + map: + textMessage: "This is my configuration" + + The JSON object can be read + through the `DATA` environment variable using `Deno.env.get("DATA");`. + + Multi-level maps are not supported at this time. + + Currently only one secret can be passed. + The secret must have a `key` called `SECURE_DATA`. + It can be accessed via the environment variable `Deno.env.get("SECURE_DATA")`. + See [Context](#context) for details. + +* **secureParameters** -- An optional field used to pass a Kubernetes secret. + The `secret` value is the Kubernetes secret name + that is mounted into the runtime and made available to functions + using the `SECURE_DATA` environment variable. + For example: + + ```yaml + secureParameters: + secret: slack-token + + See [Create secret text](#create-secret-text) for details. + +## Usage + +A Task is responsible for executing the TaskDefinition of a workload. +The execution is done by spawning a Kubernetes Job to handle a single Task. +In its state, it tracks the current status of this Kubernetes Job. + +### Context + +A context environment variable is available via `Deno.env.get("CONTEXT")`. +It can be used like this: + +```javascript +let context = Deno.env.get("CONTEXT"); + +if (contextdata.objectType == "Application") { + let application_name = contextdata.appName; + let application_version = contextdata.appVersion; +} + +if (contextdata.objectType == "Workload") { + let application_name = contextdata.appName; + let workload_name = contextdata.workloadName; + let workload_version = contextdata.workloadVersion; +} +``` + +### Create secret text + +```yaml +# kubectl create secret generic my-secret --from-literal=SECURE_DATA=foo + +apiVersion: lifecycle.keptn.sh/v1alpha3 +kind: KeptnTaskDefinition +metadata: + name: dummy-task + namespace: "default" +spec: + function: + secureParameters: + secret: my-secret + inline: + code: | + let secret_text = Deno.env.get("SECURE_DATA"); + // secret_text = "foo" +``` + +This methodology supports multiple variables +by creating a Kubernetes secret with a JSON string: + +```yaml +# kubectl create secret generic my-secret \ +# --from-literal=SECURE_DATA="{\"foo\": \"bar\", \"foo2\": \"bar2\"}" + +apiVersion: lifecycle.keptn.sh/v1alpha3 +kind: KeptnTaskDefinition +metadata: + name: dummy-task + namespace: "default" +spec: + function: + secureParameters: + secret: my-secret + inline: + code: | + let secret_text = Deno.env.get("SECURE_DATA"); + let secret_text_obj = JSON.parse(secret_text); + // secret_text_obj["foo"] = "bar" + // secret_text_obj["foo2"] = "bar2" +``` + +## Examples + +**Example 1** defines a full-fledged Deno script +within the `KeptnTaskDefinition` YAML file: + +```yaml +apiVersion: lifecycle.keptn.sh/v1alpha3 +kind: KeptnTaskDefinition +metadata: + name: hello-keptn-inline +spec: + function: + inline: + code: | + let text = Deno.env.get("DATA"); + let data; + let name; + data = JSON.parse(text); + + name = data.name + console.log("Hello, " + name + " new"); +``` + +**Example 2** fetches the Deno script from a remote webserver at runtime: + +```yaml +apiVersion: lifecycle.keptn.sh/v1alpha3 +kind: KeptnTaskDefinition +metadata: + name: hello-keptn-http +spec: + function: + httpRef: + url: <url> +``` + +See the +[sample-app/version-1](https://github.com/keptn-sandbox/lifecycle-toolkit-examples/blob/main/sample-app/version-1/app-pre-deploy.yaml) +PodtatoHead example for a more complete example. + +**Example 3** calls another defined task, +illustrating how one `KeptnTaskDefinition` can build +on top of other `KeptnTaskDefinition`s. +In this case, it calls `slack-notification-dev`, +passing `parameters` and `secureParameters` to that other task: + +```yaml +apiVersion: lifecycle.keptn.sh/v1alpha3 +kind: KeptnTaskDefinition +metadata: + name: slack-notification-dev +spec: + function: + functionRef: + name: slack-notification + parameters: + map: + textMessage: "This is my configuration" + secureParameters: + secret: slack-token +``` + +**More examples** + +* See the [operator/config/samples](https://github.com/keptn/lifecycle-toolkit/tree/main/operator/config/samples) +directory for more example `KeptnTaskDefinition` YAML files. +Separate examples are provided for each API version. +For example, the `lifecycle_v1alpha3_keptntaskdefinition` file +contains examples for the `v1alpha3` version of the lifecycle API group. + +>>>>>>> 0333070 (library -> API ) +======= +>>>>>>> 5b91097b2033a9e3c9fceefbbcca62544f9ab209 +## Files + +API Reference: + +* [KeptnTaskDefinition](../../api-ref/lifecycle/v1alpha3/#keptntaskdefinition) +* [KeptnTaskDefinitionList](../../api-ref/lifecycle/v1alpha3/#keptntaskdefinitionlist) +* [KeptnTaskDefinitionSpec](../../api-ref/lifecycle/v1alpha3/#keptntaskdefinitionspec) +* [FunctionReference](../../api-ref/lifecycle/v1alpha3/#functionreference) +* [FunctionSpec](../../api-ref/lifecycle/v1alpha3/#functionspec) +* [FunctionStatus](../../api-ref/lifecycle/v1alpha3/#functionstatus) +* [HttpReference](../../api-ref/lifecycle/v1alpha3/#httpreference) +* [Inline](../../api-ref/lifecycle/v1alpha3/#inline) + +## Differences between versions + +The `KeptnTaskDefinition` is the same for +all `v1alpha?` library versions. + +## See also + +* Link to "use-case" guide pages that do something interesting with this CRD +* Link to reference pages for any related CRDs diff --git a/docs/content/en/docs/crd-ref/_index.md b/docs/content/en/docs/crd-ref/_index.md index b96035fe53..d28ac526ab 100644 --- a/docs/content/en/docs/crd-ref/_index.md +++ b/docs/content/en/docs/crd-ref/_index.md @@ -1,7 +1,7 @@ --- -title: API Reference +title: CRD Reference description: Reference information about the KLT CRDs -weight: 100 +weight: 200 hidechildren: false # this flag hides all sub-pages in the sidebar-multicard.html --- @@ -15,10 +15,10 @@ Information that is published here has been reviewed for technical accuracy but the format and content is still evolving. We welcome your input!** -Each CRD is an object of an API library. -Keptn APIs follow the Kubernetes API versioning scheme. -and are themselves composed of objects and sub-objects. +Each CRD is an object of an +[API group](../../docs/api-ref/). By introducing CRDs, Keptn is extending the base Kubernetes API with new objects and functionality. +Keptn APIs follow API versioning conventions recommended by Kubernetes and are themselves composed of objects and sub-objects. Keptn APIs follow API versioning conventions recommended by Kubernetes. For more information, see the Kubernetes documentation: diff --git a/docs/content/en/docs/crd-ref/crd-template b/docs/content/en/docs/crd-ref/crd-template new file mode 100644 index 0000000000..cc2f96dbfa --- /dev/null +++ b/docs/content/en/docs/crd-ref/crd-template @@ -0,0 +1,35 @@ +--- +title: <crd-template> +description: <one-line description of CRD> +weight: <assign weight to create alphabetical order> +hidden: true +--- + +Copy this template to create a new CRD reference page. + +1. Replace the variable text in metadata with information for this page +1. Delete the `hidden: true` line +1. Delete these instructions from your file +1. Populate the page with appropriate content + +## Synopsis + +## Fields + +<!-- Detailed description of each field--> + +## Usage + +<!-- How this CRD is "activated". For example, which event uses this CRD --> +<!-- Instructions and guidelines for when and how to customize a CRD --> + +## Examples + +**Example 1** + +## Files + +## Differences between versions + +## See also + diff --git a/docs/content/en/docs/crd-ref/lifecycle/_index.md b/docs/content/en/docs/crd-ref/lifecycle/_index.md deleted file mode 100644 index c0fcb3d795..0000000000 --- a/docs/content/en/docs/crd-ref/lifecycle/_index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: Lifecycle API -description: Reference information about the Lifecycle API ---- diff --git a/docs/content/en/docs/tasks/write-tasks/_index.md b/docs/content/en/docs/tasks/write-tasks/_index.md deleted file mode 100644 index 5480c12ce1..0000000000 --- a/docs/content/en/docs/tasks/write-tasks/_index.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: Write Keptn Tasks -description: Learn how to use the Keptn Lifecycle Toolkit and explore basic features. -icon: concepts -layout: quickstart -weight: 20 -hidechildren: true # this flag hides all sub-pages in the sidebar-multicard.html ---- - -## Keptn Task Definition - -A `KeptnTaskDefinition` is a CRD used to define tasks that can be run by the Keptn Lifecycle Toolkit -as part of pre- and post-deployment phases of a deployment. The task definition is a [Deno](https://deno.land/) script. -In the future, we also intend to support other runtimes, especially running a container image directly. - -A task definition can be configured in three different ways: - -- inline -- referring to an HTTP script -- referring to another `KeptnTaskDefinition` - -An inline task definition looks like the following: - -```yaml -apiVersion: lifecycle.keptn.sh/v1alpha2 -kind: KeptnTaskDefinition -metadata: - name: deployment-hello -spec: - function: - inline: - code: | - console.log("Deployment Task has been executed"); -``` - -In the code section, it is possible to define a full-fletched Deno script. - -The runtime can also fetch the script on the fly from a remote webserver. For this, the CRD should look like the -following: - -```yaml -apiVersion: lifecycle.keptn.sh/v1alpha2 -kind: KeptnTaskDefinition -metadata: - name: hello-keptn-http -spec: - function: - httpRef: - url: <url> -``` - -Finally, `KeptnTaskDefinition` can build on top of other `KeptnTaskDefinition`s. -This is a common use case where a general function can be re-used in multiple places with different parameters. - -```yaml -apiVersion: lifecycle.keptn.sh/v1alpha2 -kind: KeptnTaskDefinition -metadata: - name: slack-notification-dev -spec: - function: - functionRef: - name: slack-notification - parameters: - map: - textMessage: "This is my configuration" - secureParameters: - secret: slack-token -``` - -As you might have noticed, Task Definitions also have the possibility to use input parameters. -The Lifecycle Toolkit passes the values defined inside the `map` field as a JSON object. -At the moment, multi-level maps are not supported. -The JSON object can be read through the environment variable `DATA` using `Deno.env.get("DATA");`. -Kubernetes secrets can also be passed to the function using the `secureParameters` field. - -Here, the `secret` value is the name of the K8s secret containing a field with the key `SECURE_DATA`. -The value of that field will then be available to the functions runtime via an environment variable called `SECURE_DATA`. - -For example, if you have a task function that should make use of secret data, you must first ensure that the secret -containing the `SECURE_DATA` key exists, as e.g.: - -```yaml -apiVersion: v1 -kind: Secret -metadata: - name: deno-demo-secret - namespace: default -type: Opaque -data: - SECURE_DATA: YmFyCg== # base64 encoded string, e.g. 'bar' -``` - -Then, you can make use of that secret as follows: - -```yaml -apiVersion: lifecycle.keptn.sh/v1alpha3 -kind: KeptnTaskDefinition -metadata: - name: deployment-hello - namespace: "default" -spec: - function: - secureParameters: - secret: deno-demo-secret - inline: - code: | - console.log("Deployment Hello Task has been executed"); - - let foo = Deno.env.get('SECURE_DATA'); - console.log(foo); - Deno.exit(0); -```