diff --git a/docs/examples-external-articles.md b/docs/examples-external-articles.md index 84dc47c9..d26bac74 100644 --- a/docs/examples-external-articles.md +++ b/docs/examples-external-articles.md @@ -1,7 +1,5 @@ # External Articles -Links to external articles about Cluster.dev: - * [Cluster.dev: All-in-One Tool for Cloud Native Infrastructure](https://itnext.io/cluster-dev-all-in-one-tool-for-cloud-native-infrastructure-636ed6ba8e28) * [Mastering Cloud Infrastructure with Cluster.dev](https://medium.com/@AlexanderObregon/mastering-cloud-infrastructure-with-cluster-dev-37cc88a8edc0) @@ -14,4 +12,6 @@ Links to external articles about Cluster.dev: * [Deploy Kubernetes in Minutes: Effortless Infrastructure Creation and Application Deployment with Cluster.dev and Helm Charts](https://aws.plainenglish.io/deploy-kubernetes-in-minutes-effortless-infrastructure-creation-and-application-deployment-with-94141697fd59) -* [Cluster.dev: Is it the right Kubernetes Bootstrapping tool for you?](https://itnext.io/cluster-dev-is-it-the-right-kubernetes-bootstrapping-tool-for-you-6dd5e92aa9a0) \ No newline at end of file +* [Cluster.dev: Is it the right Kubernetes Bootstrapping tool for you?](https://itnext.io/cluster-dev-is-it-the-right-kubernetes-bootstrapping-tool-for-you-6dd5e92aa9a0) + +* [Cluster.dev: Expanding the Options for SaaS Deployment](https://thenewstack.io/cluster-dev-expanding-the-options-for-saas-deployment/) \ No newline at end of file diff --git a/docs/how-does-cdev-work.md b/docs/how-does-cdev-work.md index 2f9acf99..7c5e968b 100644 --- a/docs/how-does-cdev-work.md +++ b/docs/how-does-cdev-work.md @@ -13,7 +13,7 @@ Capabilities: ## Basic diagram -![cdev diagram](./images/cdev-base-diagram-shema1_red.png) + ## Templating diff --git a/docs/index.md b/docs/index.md index 0e8487c9..f61487d8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,11 +15,11 @@ Cluster.dev is an open-source tool designed to manage cloud native infrastructur Stack templates are composed of [units](https://docs.cluster.dev/units-overview/) - Lego-like building blocks responsible for passing variables to a particular technology. -![cdev unit example diagram](./images/cdev-unit-example.png) + Templates define infrastructure patterns or even the whole platform. -![cdev template example diagram](./images/cdev-template-example.png) + ## Features diff --git a/docs/stack-templates-overview.md b/docs/stack-templates-overview.md index 81c992f9..f0c10b68 100644 --- a/docs/stack-templates-overview.md +++ b/docs/stack-templates-overview.md @@ -1,6 +1,6 @@ # Overview -![cdev template diagram](./images/cdev-template-shema2.png) + ## Description diff --git a/docs/units-helm.md b/docs/units-helm.md index 9aac7d45..3e5636df 100644 --- a/docs/units-helm.md +++ b/docs/units-helm.md @@ -2,6 +2,8 @@ Describes [Terraform Helm provider](https://registry.terraform.io/providers/hashicorp/helm/latest/docs) invocation. +## Example usage + In the example below we use `helm` unit to deploy Argo CD to a Kubernetes cluster: ```yaml @@ -31,7 +33,7 @@ units: global.image.tag: v1.8.3 # (same as values.set ) ``` -In addition to common options the following are available: +## Options * `force_apply` - *bool*, *optional*. By default is false. If set to true, the unit will be applied when any dependent unit is changed. @@ -44,38 +46,43 @@ In addition to common options the following are available: * `additional_options` - *map of any*, *optional*. Corresponds to [Terraform helm_release resource options](https://registry.terraform.io/providers/hashicorp/helm/latest/docs/resources/release#argument-reference). Will be passed as is. -* `values` - *array*, *optional*. List of values (file name or values data) to be passed to Helm. Values will be merged, in order, as Helm does with multiple -f options. +* [`values`](#values) - *array*, *optional*. List of values (file name or values data) to be passed to Helm. Values will be merged, in order, as Helm does with multiple -f options. For details see below. - * `set` - *map of any*, *required one of set/file*. Set of Helm values. This option allows you to transfer the value of the Helm chart without saving it to a file. +* `inputs` - *map of any*, *optional*. A map that represents [Terraform helm_release sets](https://registry.terraform.io/providers/hashicorp/helm/latest/docs/resources/release#set). This block allows to use functions `remoteState` and `insertYAML`. +For example: - * `file` - *string*, *required one of set/file*. Path to the values file. + ```yaml + inputs: + global.image.tag: v1.8.3 + service.type: LoadBalancer + ``` - * `apply_template` - *bool*, *optional*. Defines whether a template should be applied to the values file. By default is set to `true`. Used only with `file` option. + Corresponds to: -* `inputs` - *map of any*, *optional*. A map that represents [Terraform helm_release sets](https://registry.terraform.io/providers/hashicorp/helm/latest/docs/resources/release#set). This block allows to use functions `remoteState` and `insertYAML`. For example: + ```yaml + set { + name = "global.image.tag" + value = "v1.8.3" + } + set { + name = "service.type" + value = "LoadBalancer" + } + ``` - ```yaml - inputs: - global.image.tag: v1.8.3 - service.type: LoadBalancer - ``` +* [`provider_conf`](#provider_conf) - configuration block that describes authorization in Kubernetes. Supports the same arguments as the [Terraform Kubernetes provider](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs#argument-reference). It is allowed to use the `remoteState` function and Cluster.dev templates within the block. For details see below. - Corresponds to: +### `values` - ```yaml - set { - name = "global.image.tag" - value = "v1.8.3" - } - set { - name = "service.type" - value = "LoadBalancer" - } - ``` +* `set` - *map of any*, *required one of set/file*. Set of Helm values. This option allows you to transfer the value of the Helm chart without saving it to a file. -* `provider_conf` - configuration block that describes authorization in Kubernetes. Supports the same arguments as the [Terraform Kubernetes provider](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs#argument-reference). It is allowed to use the `remoteState` function and Cluster.dev templates within the block. +* `file` - *string*, *required one of set/file*. Path to the values file. - Example usage: +* `apply_template` - *bool*, *optional*. Defines whether a template should be applied to the values file. By default is set to `true`. Used only with `file` option. + +### `provider_conf` + +Example usage: ```yaml name: cert-manager-issuer @@ -88,46 +95,48 @@ In addition to common options the following are available: password: "secretPassword" ``` - * `host` - *optional*. The hostname (in form of URI) of the Kubernetes API. Can be sourced from `KUBE_HOST`. +* `host` - *optional*. The hostname (in form of URI) of the Kubernetes API. Can be sourced from `KUBE_HOST`. + +* `username` - *optional*. The username to use for HTTP basic authentication when accessing the Kubernetes API. Can be sourced from `KUBE_USER`. + +* `password` - *optional*. The password to use for HTTP basic authentication when accessing the Kubernetes API. Can be sourced from `KUBE_PASSWORD`. + +* `insecure` - *optional*. Whether the server should be accessed without verifying the TLS certificate. Can be sourced from `KUBE_INSECURE`. Defaults to `false`. - * `username` - *optional*. The username to use for HTTP basic authentication when accessing the Kubernetes API. Can be sourced from `KUBE_USER`. +* `tls_server_name` - *optional*. Server name passed to the server for SNI and is used in the client to check server certificates against. Can be sourced from `KUBE_TLS_SERVER_NAME`. - * `password` - *optional*. The password to use for HTTP basic authentication when accessing the Kubernetes API. Can be sourced from `KUBE_PASSWORD`. +* `client_certificate` - *optional*. PEM-encoded client certificate for TLS authentication. Can be sourced from `KUBE_CLIENT_CERT_DATA`. - * `insecure` - *optional*. Whether the server should be accessed without verifying the TLS certificate. Can be sourced from `KUBE_INSECURE`. Defaults to `false`. +* `client_key` - *optional*. PEM-encoded client certificate key for TLS authentication. Can be sourced from `KUBE_CLIENT_KEY_DATA`. - * `tls_server_name` - *optional*. Server name passed to the server for SNI and is used in the client to check server certificates against. Can be sourced from `KUBE_TLS_SERVER_NAME`. +* `client_ca_certificate` - *optional*. PEM-encoded root certificates bundle for TLS authentication. Can be sourced from `KUBE_CLUSTER_CA_CERT_DATA`. - * `client_certificate` - *optional*. PEM-encoded client certificate for TLS authentication. Can be sourced from `KUBE_CLIENT_CERT_DATA`. +* `config_path` - *optional*. A path to a kube config file. Can be sourced from `KUBE_CONFIG_PATH`. - * `client_key` - *optional*. PEM-encoded client certificate key for TLS authentication. Can be sourced from `KUBE_CLIENT_KEY_DATA`. +* `config_paths` - *optional*. A list of paths to the kube config files. Can be sourced from `KUBE_CONFIG_PATHS`. - * `client_ca_certificate` - *optional*. PEM-encoded root certificates bundle for TLS authentication. Can be sourced from `KUBE_CLUSTER_CA_CERT_DATA`. +* `config_context` - *optional*. Context to choose from the config file. Can be sourced from `KUBE_CTX`. - * `config_path` - *optional*. A path to a kube config file. Can be sourced from `KUBE_CONFIG_PATH`. +* `config_context_auth_info` - *optional*. Authentication info context of the kube config (name of the kubeconfig user, `--user` flag in `kubectl`). Can be sourced from `KUBE_CTX_AUTH_INFO`. - * `config_paths` - *optional*. A list of paths to the kube config files. Can be sourced from `KUBE_CONFIG_PATHS`. +* `config_context_cluster` - *optional*. Cluster context of the kube config (name of the kubeconfig cluster, `--cluster` flag in `kubectl`). Can be sourced from `KUBE_CTX_CLUSTER`. - * `config_context` - *optional*. Context to choose from the config file. Can be sourced from `KUBE_CTX`. +* `token` - *optional*. Token of your service account. Can be sourced from `KUBE_TOKEN` - * `config_context_auth_info` - *optional*. Authentication info context of the kube config (name of the kubeconfig user, `--user` flag in `kubectl`). Can be sourced from `KUBE_CTX_AUTH_INFO`. +* `proxy_url` - *optional*. URL to the proxy to be used for all API requests. URLs with "http", "https", and "socks5" schemes are supported. Can be sourced from `KUBE_PROXY_URL`. - * `config_context_cluster` - *optional*. Cluster context of the kube config (name of the kubeconfig cluster, `--cluster` flag in `kubectl`). Can be sourced from `KUBE_CTX_CLUSTER`. +* `exec` - *optional*. Configuration block to use an [exec-based credential plugin](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins), e.g. call an external command to receive user credentials. - * `token` - *optional*. Token of your service account. Can be sourced from `KUBE_TOKEN` + * `api_version` - *required*. API version to use when decoding the ExecCredentials resource, e.g. `client.authentication.k8s.io/v1beta1`. - * `proxy_url` - *optional*. URL to the proxy to be used for all API requests. URLs with "http", "https", and "socks5" schemes are supported. Can be sourced from `KUBE_PROXY_URL`. + * `command` - *required*. Command to execute. - * `exec` - *optional*. Configuration block to use an [exec-based credential plugin](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins), e.g. call an external command to receive user credentials. + * `args` - *optional*. List of arguments to pass when executing the plugin. - * `api_version` - *required*. API version to use when decoding the ExecCredentials resource, e.g. `client.authentication.k8s.io/v1beta1`. + * `env` - *optional*. Map of environment variables to set when executing the plugin. - * `command` - *required*. Command to execute. +* `ignore_annotations` - *optional*. List of Kubernetes metadata annotations to ignore across all resources handled by this provider for situations where external systems are managing certain resource annotations. This option does not affect annotations within a template block. Each item is a regular expression. - * `args` - *optional*. List of arguments to pass when executing the plugin. +* `ignore_labels` - *optional*. List of Kubernetes metadata labels to ignore across all resources handled by this provider for situations where external systems are managing certain resource labels. This option does not affect annotations within a template block. Each item is a regular expression. - * `env` - *optional*. Map of environment variables to set when executing the plugin. - - * `ignore_annotations` - *optional*. List of Kubernetes metadata annotations to ignore across all resources handled by this provider for situations where external systems are managing certain resource annotations. This option does not affect annotations within a template block. Each item is a regular expression. - * `ignore_labels` - *optional*. List of Kubernetes metadata labels to ignore across all resources handled by this provider for situations where external systems are managing certain resource labels. This option does not affect annotations within a template block. Each item is a regular expression. \ No newline at end of file diff --git a/docs/units-k8s-manifest.md b/docs/units-k8s-manifest.md index 1c468043..b1854825 100644 --- a/docs/units-k8s-manifest.md +++ b/docs/units-k8s-manifest.md @@ -6,7 +6,7 @@ Applies Kubernetes resources from manifests. -Example: +## Example usage ```yaml - name: kubectl-test2 diff --git a/docs/units-kubernetes.md b/docs/units-kubernetes.md index 1443e17d..b9b17407 100644 --- a/docs/units-kubernetes.md +++ b/docs/units-kubernetes.md @@ -8,8 +8,7 @@ The unit automatically converts Kubernetes manifests into Terraform resources by To deploy to Kubernetes using Terraform, use this unit to automatically convert YAML files into ready-to-use HCL code. - -Example: +## Example usage ```yaml units: @@ -20,17 +19,21 @@ units: depends_on: this.argocd ``` +## Options + * `force_apply` - *bool*, *optional*. By default is false. If set to true, the unit will be applied when any dependent unit is changed. * `source` - *string*, *required*. Path to Kubernetes manifest that will be converted into a representation of Kubernetes provider. **Source file will be rendered with the stack template, and also allows to use functions `remoteState` and `insertYAML`**. * `kubeconfig` - *string*, *required*. Path to the kubeconfig file, which is relative to the directory where the unit was executed. -* `provider_conf` - configuration block that describes authorization in Kubernetes. Supports the same arguments as the [Terraform Kubernetes provider](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs#argument-reference). It is allowed to use the `remoteState` function and Cluster.dev templates within the block. +* [`provider_conf`](#provider_conf) - configuration block that describes authorization in Kubernetes. Supports the same arguments as the [Terraform Kubernetes provider](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs#argument-reference). It is allowed to use the `remoteState` function and Cluster.dev templates within the block. For details see below. + +### `provider_conf` - Example usage: +Example usage: - ```yaml + ```yaml name: cert-manager-issuer type: kubernetes depends_on: this.cert-manager @@ -39,52 +42,51 @@ units: host: k8s.example.com username: "user" password: "secretPassword" - ``` + ``` - * `host` - *optional*. The hostname (in form of URI) of the Kubernetes API. Can be sourced from `KUBE_HOST`. +* `host` - *optional*. The hostname (in form of URI) of the Kubernetes API. Can be sourced from `KUBE_HOST`. - * `username` - *optional*. The username to use for HTTP basic authentication when accessing the Kubernetes API. Can be sourced from `KUBE_USER`. +* `username` - *optional*. The username to use for HTTP basic authentication when accessing the Kubernetes API. Can be sourced from `KUBE_USER`. - * `password` - *optional*. The password to use for HTTP basic authentication when accessing the Kubernetes API. Can be sourced from `KUBE_PASSWORD`. +* `password` - *optional*. The password to use for HTTP basic authentication when accessing the Kubernetes API. Can be sourced from `KUBE_PASSWORD`. - * `insecure` - *optional*. Whether the server should be accessed without verifying the TLS certificate. Can be sourced from `KUBE_INSECURE`. Defaults to `false`. +* `insecure` - *optional*. Whether the server should be accessed without verifying the TLS certificate. Can be sourced from `KUBE_INSECURE`. Defaults to `false`. - * `tls_server_name` - *optional*. Server name passed to the server for SNI and is used in the client to check server certificates against. Can be sourced from `KUBE_TLS_SERVER_NAME`. +* `tls_server_name` - *optional*. Server name passed to the server for SNI and is used in the client to check server certificates against. Can be sourced from `KUBE_TLS_SERVER_NAME`. - * `client_certificate` - *optional*. PEM-encoded client certificate for TLS authentication. Can be sourced from `KUBE_CLIENT_CERT_DATA`. +* `client_certificate` - *optional*. PEM-encoded client certificate for TLS authentication. Can be sourced from `KUBE_CLIENT_CERT_DATA`. - * `client_key` - *optional*. PEM-encoded client certificate key for TLS authentication. Can be sourced from `KUBE_CLIENT_KEY_DATA`. +* `client_key` - *optional*. PEM-encoded client certificate key for TLS authentication. Can be sourced from `KUBE_CLIENT_KEY_DATA`. - * `client_ca_certificate` - *optional*. PEM-encoded root certificates bundle for TLS authentication. Can be sourced from `KUBE_CLUSTER_CA_CERT_DATA`. +* `client_ca_certificate` - *optional*. PEM-encoded root certificates bundle for TLS authentication. Can be sourced from `KUBE_CLUSTER_CA_CERT_DATA`. - * `config_path` - *optional*. A path to a kube config file. Can be sourced from `KUBE_CONFIG_PATH`. +* `config_path` - *optional*. A path to a kube config file. Can be sourced from `KUBE_CONFIG_PATH`. - * `config_paths` - *optional*. A list of paths to the kube config files. Can be sourced from `KUBE_CONFIG_PATHS`. +* `config_paths` - *optional*. A list of paths to the kube config files. Can be sourced from `KUBE_CONFIG_PATHS`. - * `config_context` - *optional*. Context to choose from the config file. Can be sourced from `KUBE_CTX`. +* `config_context` - *optional*. Context to choose from the config file. Can be sourced from `KUBE_CTX`. - * `config_context_auth_info` - *optional*. Authentication info context of the kube config (name of the kubeconfig user, `--user` flag in `kubectl`). Can be sourced from `KUBE_CTX_AUTH_INFO`. +* `config_context_auth_info` - *optional*. Authentication info context of the kube config (name of the kubeconfig user, `--user` flag in `kubectl`). Can be sourced from `KUBE_CTX_AUTH_INFO`. - * `config_context_cluster` - *optional*. Cluster context of the kube config (name of the kubeconfig cluster, `--cluster` flag in `kubectl`). Can be sourced from `KUBE_CTX_CLUSTER`. +* `config_context_cluster` - *optional*. Cluster context of the kube config (name of the kubeconfig cluster, `--cluster` flag in `kubectl`). Can be sourced from `KUBE_CTX_CLUSTER`. - * `token` - *optional*. Token of your service account. Can be sourced from `KUBE_TOKEN` +* `token` - *optional*. Token of your service account. Can be sourced from `KUBE_TOKEN` - * `proxy_url` - *optional*. URL to the proxy to be used for all API requests. URLs with "http", "https", and "socks5" schemes are supported. Can be sourced from `KUBE_PROXY_URL`. +* `proxy_url` - *optional*. URL to the proxy to be used for all API requests. URLs with "http", "https", and "socks5" schemes are supported. Can be sourced from `KUBE_PROXY_URL`. - * `exec` - *optional*. Configuration block to use an [exec-based credential plugin](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins), e.g. call an external command to receive user credentials. +* `exec` - *optional*. Configuration block to use an [exec-based credential plugin](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins), e.g. call an external command to receive user credentials. - * `api_version` - *required*. API version to use when decoding the ExecCredentials resource, e.g. `client.authentication.k8s.io/v1beta1`. + * `api_version` - *required*. API version to use when decoding the ExecCredentials resource, e.g. `client.authentication.k8s.io/v1beta1`. - * `command` - *required*. Command to execute. + * `command` - *required*. Command to execute. - * `args` - *optional*. List of arguments to pass when executing the plugin. + * `args` - *optional*. List of arguments to pass when executing the plugin. - * `env` - *optional*. Map of environment variables to set when executing the plugin. - - * `ignore_annotations` - *optional*. List of Kubernetes metadata annotations to ignore across all resources handled by this provider for situations where external systems are managing certain resource annotations. This option does not affect annotations within a template block. Each item is a regular expression. + * `env` - *optional*. Map of environment variables to set when executing the plugin. - * `ignore_labels` - *optional*. List of Kubernetes metadata labels to ignore across all resources handled by this provider for situations where external systems are managing certain resource labels. This option does not affect annotations within a template block. Each item is a regular expression. +* `ignore_annotations` - *optional*. List of Kubernetes metadata annotations to ignore across all resources handled by this provider for situations where external systems are managing certain resource annotations. This option does not affect annotations within a template block. Each item is a regular expression. +* `ignore_labels` - *optional*. List of Kubernetes metadata labels to ignore across all resources handled by this provider for situations where external systems are managing certain resource labels. This option does not affect annotations within a template block. Each item is a regular expression. diff --git a/docs/units-overview.md b/docs/units-overview.md index 89f1a3aa..82f3ba0b 100644 --- a/docs/units-overview.md +++ b/docs/units-overview.md @@ -1,6 +1,6 @@ # Overview -![cdev unit diagram](./images/cdev-unit-shema4.png) + ## Description diff --git a/docs/units-printer.md b/docs/units-printer.md index 293a903a..c43e79e5 100644 --- a/docs/units-printer.md +++ b/docs/units-printer.md @@ -6,7 +6,7 @@ This unit exposes outputs that can be used in other units and stacks. If named *output*, the unit will have all its outputs displayed when running `cdev apply` or `cdev output`. -Example: +## Example usage ```yaml units: @@ -17,6 +17,8 @@ units: name: {{ .variables.name }} ``` +## Options + * `outputs` - *any*, *required* - a map that represents data to be printed in the log. The block **allows to use functions `remoteState` and `insertYAML`**. * `force_apply` - *bool*, *optional*. By default is false. If set to true, the unit will be applied when any dependent unit is changed. diff --git a/docs/units-shell.md b/docs/units-shell.md index a1b04860..52228269 100644 --- a/docs/units-shell.md +++ b/docs/units-shell.md @@ -2,6 +2,8 @@ Executes Shell commands and scripts. +## Example usage + Example of a `shell` unit that creates an index.html file with a greeting message and downloads the file into an S3 bucket. The bucket name is passed as a variable: ```yaml @@ -66,61 +68,77 @@ units: * `work_dir` - *string*, *required*. The working directory within which the code of the unit will be executed. -* `apply` - *optional*, *map*. Describes commands to be executed when running `cdev apply`. +* [`apply`](#apply) - *optional*, *map*. Describes commands to be executed when running `cdev apply`. For details see below. + +* [`plan`](#plan) - *optional*, *map*. Describes commands to be executed when running `cdev plan`. For details see below. + +* [`destroy`](#destroy) - *optional*, *map*. Describes commands to be executed when running `cdev destroy`. For details see below. + +* [`outputs`](#outputs) - *optional*, *map*. Describes how to get outputs from a command. For details see below. + +* `create_files` - *list of files*, *optional*. The list of files that have to be saved in the state in case of their changing. + +* [`pre_hook` and `post_hook` blocks](#pre_hook-and-post_hook-blocks): describe the shell commands to be executed before and after the unit, respectively. The commands will be executed in the same context as the actions of the unit. Environment variables are common to the shell commands, the pre_hook and post_hook scripts, and the unit execution. You can export a variable in the pre_hook and it will be available in the post_hook or in the unit. For details see below. - * `init` - *optional*. Describes commands to be executed prior to running `cdev apply`. +### `apply` - * `commands` - *list of strings*, *required*. The list of commands to be executed when running `cdev apply`. +* `init` - *optional*. Describes commands to be executed prior to running `cdev apply`. -* `plan` - *optional*, *map*. Describes commands to be executed when running `cdev plan`. +* `commands` - *list of strings*, *required*. The list of commands to be executed when running `cdev apply`. - * `init` - *optional*. Describes commands to be executed prior to running `cdev plan`. +### `plan` + +* `init` - *optional*. Describes commands to be executed prior to running `cdev plan`. - * `commands` - *list of strings*, *required*. The list of commands to be executed when running `cdev plan`. +* `commands` - *list of strings*, *required*. The list of commands to be executed when running `cdev plan`. -* `destroy` - *optional*, *map*. Describes commands to be executed when running `cdev destroy`. +### `destroy` - * `init` - *optional*. Describes commands to be executed prior to running `cdev destroy`. +* `init` - *optional*. Describes commands to be executed prior to running `cdev destroy`. - * `commands` - *list of strings*, *required*. The list of commands to be executed when running `cdev destroy`. +* `commands` - *list of strings*, *required*. The list of commands to be executed when running `cdev destroy`. -* `outputs` - *optional*, *map*. Describes how to get outputs from a command. +### `outputs` - * `type` - *string*, *required*. A type of format to deliver the output. Could have 3 options: JSON, regexp, separator. According to the type specified, further options will differ. +* `type` - *string*, *required*. A type of format to deliver the output. Could have 3 options: JSON, regexp, separator. According to the type specified, further options will differ. - * `JSON` - if the `type` is defined as JSON, outputs will be parsed as key-value JSON. This type of output makes all other options not required. +* `JSON` - if the `type` is defined as JSON, outputs will be parsed as key-value JSON. This type of output makes all other options not required. - * `regexp` - if the `type` is defined as regexp, this introduces an additional required option `regexp`. Regexp is a regular expression which defines how to parse each line in the module output. Example: +* `regexp` - if the `type` is defined as regexp, this introduces an additional required option `regexp`. Regexp is a regular expression which defines how to parse each line in the module output. Example: - ```yaml - outputs: # how to get outputs - type: regexp - regexp: "^(.*)=(.*)$" - command: | - echo "key1=val1\nkey2=val2" - ``` + ```yaml + outputs: # how to get outputs + type: regexp + regexp: "^(.*)=(.*)$" + command: | + echo "key1=val1\nkey2=val2" + ``` - * `separator` - if the `type` is defined as separator, this introduces an additional option `separator` (*string*). Separator is a symbol that defines how a line is divided in two parts: the key and the value. +* `separator` - if the `type` is defined as separator, this introduces an additional option `separator` (*string*). Separator is a symbol that defines how a line is divided in two parts: the key and the value. - ```yaml - outputs: # how to get outputs - type: separator - separator: "=" - command: | - echo "key1=val1\nkey2=val2" - ``` - * `command` - *string*, *optional*. The command to take the outputs from. Is used regardless of the type option. If the command is not defined, cdev takes the outputs from the `apply` command. + ```yaml + outputs: # how to get outputs + type: separator + separator: "=" + command: | + echo "key1=val1\nkey2=val2" + ``` +* `command` - *string*, *optional*. The command to take the outputs from. Is used regardless of the type option. If the command is not defined, cdev takes the outputs from the `apply` command. -* `create_files` - *list of files*, *optional*. The list of files that have to be saved in the state in case of their changing. +### `pre_hook` and `post_hook` blocks + +* `command` - *string*. Shell command in text format. Will be executed in Bash -c "command". Can be used if the "script" option is not used. One of `command` or `script` is required. + +* `script` - *string*. Path to shell script file which is relative to template directory. Can be used if the "command" option is not used. One of `command` or `script` is required. + +* `on_apply` *bool*, *optional*. Turn off/on when unit applying. **Default: "true"**. + +* `on_destroy` - *bool*, *optional*. Turn off/on when unit destroying. **Default: "false"**. + +* `on_plan` - *bool*, *optional*. Turn off/on when unit plan executing. **Default: "false"**. -* `pre_hook` and `post_hook` blocks: describe the shell commands to be executed before and after the unit, respectively. The commands will be executed in the same context as the actions of the unit. Environment variables are common to the shell commands, the pre_hook and post_hook scripts, and the unit execution. You can export a variable in the pre_hook and it will be available in the post_hook or in the unit. - * `command` - *string*. Shell command in text format. Will be executed in Bash -c "command". Can be used if the "script" option is not used. One of `command` or `script` is required. - * `script` - *string*. Path to shell script file which is relative to template directory. Can be used if the "command" option is not used. One of `command` or `script` is required. - * `on_apply` *bool*, *optional*. Turn off/on when unit applying. **Default: "true"**. - * `on_destroy` - *bool*, *optional*. Turn off/on when unit destroying. **Default: "false"**. - * `on_plan` - *bool*, *optional*. Turn off/on when unit plan executing. **Default: "false"**. diff --git a/docs/units-terraform.md b/docs/units-terraform.md index f2e22527..ae826f74 100644 --- a/docs/units-terraform.md +++ b/docs/units-terraform.md @@ -2,6 +2,8 @@ Describes direct invocation of Terraform modules. +## Example usage + In the example below we use the `tfmodule` unit to create an S3 bucket for hosting a static web page. The `tfmodule` unit applies a dedicated Terraform module. ```yaml @@ -36,7 +38,7 @@ units: } ``` -In addition to common options the following are available: +## Options * `source` - *string*, *required*. Terraform module [source](https://www.terraform.io/docs/language/modules/syntax.html#source). **It is not allowed to use local folders in source!** diff --git a/mkdocs.yml b/mkdocs.yml index 48fd939c..d5fca9b6 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -10,29 +10,23 @@ nav: - Overview: - What Is Cluster.dev?: index.md - How Does It Work?: how-does-cdev-work.md - - Getting Started: - - Overview: get-started-overview.md - - Quick Start on AWS: get-started-cdev-aws.md - - Quick Start on Azure: get-started-cdev-azure.md - - Quick Start on GCP: get-started-cdev-gcp.md - - Quick Start with Kubernetes: get-started-cdev-helm.md - - Examples: - - Overview: examples-overview.md - - AWS-EKS: examples-aws-eks.md - - AWS-K3s: examples-aws-k3s.md - - Azure-AKS: examples-azure-aks.md - - GCP-GKE: examples-gcp-gke.md - - AWS-K3s Prometheus: examples-aws-k3s-prometheus.md - - DO-K8s: examples-do-k8s.md - - Modify AWS-EKS: examples-modify-aws-eks.md - - HF LLM in EKS: examples-eks-model.md - - External Articles: examples-external-articles.md - Installation and Upgrade: installation-upgrade.md - - Cluster.dev vs. Others: - - Cluster.dev vs. Terragrunt: cdev-vs-terragrunt.md - - Cluster.dev vs. Helmfile: cdev-vs-helmfile.md - - Cluster.dev vs. Terraform: cdev-vs-terraform.md - - Cluster.dev vs. Pulumi & Crossplane: cdev-vs-pulumi.md + - Getting Started: + - Overview: get-started-overview.md + - Quick Start on AWS: get-started-cdev-aws.md + - Quick Start on Azure: get-started-cdev-azure.md + - Quick Start on GCP: get-started-cdev-gcp.md + - Quick Start with Kubernetes: get-started-cdev-helm.md + - Examples: + - Overview: examples-overview.md + - AWS-EKS: examples-aws-eks.md + - AWS-K3s: examples-aws-k3s.md + - Azure-AKS: examples-azure-aks.md + - GCP-GKE: examples-gcp-gke.md + - AWS-K3s Prometheus: examples-aws-k3s-prometheus.md + - DO-K8s: examples-do-k8s.md + - Modify AWS-EKS: examples-modify-aws-eks.md + - HF LLM in EKS: examples-eks-model.md - Reference: - Structure: - Overview: structure-overview.md @@ -62,6 +56,13 @@ nav: - Environment variables: env-variables.md - How-to Articles: - Use Different Terraform versions: howto-tf-versions.md + - Resources: + - External Articles: examples-external-articles.md + - Cluster.dev vs. Other Technologies: + - Cluster.dev vs. Terragrunt: cdev-vs-terragrunt.md + - Cluster.dev vs. Helmfile: cdev-vs-helmfile.md + - Cluster.dev vs. Terraform: cdev-vs-terraform.md + - Cluster.dev vs. Pulumi & Crossplane: cdev-vs-pulumi.md markdown_extensions: