Skip to content

Commit

Permalink
release v0.9.6 doc update
Browse files Browse the repository at this point in the history
  • Loading branch information
anastyakulyk committed Sep 25, 2024
1 parent 1558d6e commit a36a6a3
Show file tree
Hide file tree
Showing 6 changed files with 15 additions and 11 deletions.
2 changes: 1 addition & 1 deletion docs/stack-templates-overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

A stack template is a `yaml` file that tells Cluster.dev which units to run and how. It is a core Cluster.dev resource that makes for its flexibility. Stack templates use Go template language to allow you customise and select the units you want to run.

The stack template's config files are stored within the stack template directory that could be located either locally or in a Git repo. Cluster.dev reads all _./*.yaml files from the directory (except for the yaml/yml files specified within the [.cdevignore](#cdevignore)), renders a stack template with the project's data, parse the `yaml` file and loads [units](https://docs.cluster.dev/units-overview/) - the most primitive elements of a stack template.
The stack template's config files are stored within the stack template directory that could be located either locally or in a Git repo. Cluster.dev reads all _./*.yaml files from the directory (except for the yaml/yml files specified within the [.cdevignore](#cdevignore)), renders a stack template with the project's data, parses the `yaml` file and loads [units](https://docs.cluster.dev/units-overview/) - the most primitive elements of a stack template.

A stack template represents a `yaml` structure with an array of different invocation units. Common view:

Expand Down
2 changes: 1 addition & 1 deletion docs/structure-overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

[Stack template](https://docs.cluster.dev/stack-templates-overview/) – a set of units linked together into one infrastructure pattern (describes whole infrastructure). You can think of it like a complex Helm chart or compound Terraform Module.

[Stack](https://docs.cluster.dev/structure-stack/) – a set of variables that would be applied to a stack template (like `values.yaml` in Helm or `tfvars` file in Terraform). Is used to configure the resulting infrastructure.
[Stack](https://docs.cluster.dev/structure-stack/) – a set of variables that would be applied to a stack template (like `values.yaml` in Helm or `tfvars` file in Terraform). IT is used to configure the resulting infrastructure.

[Project](https://docs.cluster.dev/structure-project/) – a high-level metaobject that could arrange multiple stacks and keep global variables. An infrastructure can consist of multiple stacks, while a project acts like an umbrella object for these stacks.

Expand Down
4 changes: 4 additions & 0 deletions docs/templating.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,3 +26,7 @@ The templating process could be described as follows:

7. Executing the project.

!!! Note
Starting from the [release version v0.9.6](https://github.com/shalb/cluster.dev/releases/tag/v0.9.6), it is possible to source variables into stack templates directly from `project.yaml`.


12 changes: 4 additions & 8 deletions docs/units-k8s-manifest.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ Applies Kubernetes resources from manifests.

* `create_namespaces` - *bool*, *optional*. By default is false. If set to true, cdev will create namespaces required for the unit (i.e. the namespaces listed in manifests and the one specified within the `namespace` option), in case they don't exist.

* `path` - *required*, *string*. Indicates the resources that are to be applied: a file (in case of a file path), a directory recursively (in case of a directory path) or URL. In case of URL path the unit will download the resources by the link and then apply them.
* `path` - *required*, *string*. Indicates the resources that are to be applied: a file (in case of a file path), a directory recursively (in case of a directory path) or URL. In case of URL path, the unit will download the resources by the link and then apply them.

Example of URL `path`:

Expand All @@ -39,16 +39,12 @@ Applies Kubernetes resources from manifests.
kubeconfig: {{ output "this.kubeconfig.kubeconfig_path" }}
```

* `apply_template` - *bool*. By default is set to `true`. See [Templating usage](#templating-usage) below.
* `apply_template` - *bool*. By default is set to `true`. Enables applying [templating](https://docs.cluster.dev/templating/) to all Kubernetes manifests located in the specified `path`.

* `kubeconfig` - *optional*. Specifies the path to a kubeconfig file. See [How to get kubeconfig](#how-to-get-kubeconfig) subsection below.

* `kubectl_opts` - *optional*. Lists additional arguments of the `kubectl` command.

## Templating usage

As manifests are part of a stack template, they also maintain [templating](https://docs.cluster.dev/templating/) options. Specifying the `apply_template` option enables you to use templating in all Kubernetes manifests located with the specified `path`.

## How to get kubeconfig

There are several ways to get a kubeconfig from a cluster and pass it to the units that require it (for example, `helm`, `K8s-manifest`). The recommended way is to use the `shell` unit with the option `force_apply`. Here is an example of such unit:
Expand Down Expand Up @@ -79,13 +75,13 @@ The kubeconfig can then be passed as an output to other units:
kubeconfig: {{ output "this.kubeconfig.kubeconfig_path" }}
```

An alternative (but not recommended) way is to create a yaml hook in a stack template that would take the required set of commands:
An alternative (but not recommended) way is to create a `yaml` hook in a stack template that would take the required set of commands:

```yaml
_: &getKubeconfig "rm -f ../kubeconfig_{{ .name }}; aws eks --region {{ .variables.region }} update-kubeconfig --name {{ .name }} --kubeconfig ../kubeconfig_{{ .name }}"
```

and execute it with a pre-hook in each unit:
And execute it with a pre-hook in each unit:

```yaml
- name: cert-manager-issuer
Expand Down
4 changes: 3 additions & 1 deletion docs/units-kubernetes.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,10 +23,12 @@ units:
* `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`**.
* `source` - *string*, *required*. Similar to option `path` in the `k8s-manifest` unit. Indicates the resources that are to be applied: a file (in case of a file path), a directory recursively (in case of a directory path) or URL. In case of URL path, the unit will download the resources by the link and then apply them. **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.

* `apply_template` - *bool*. By default is set to `true`. Enables applying [templating](https://docs.cluster.dev/templating/) to all Kubernetes manifests located in the specified `path`.

* [`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`
Expand Down
2 changes: 2 additions & 0 deletions docs/variables.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@ variables:
The values of the variables are passed to a stack template to configure the resulting infrastructure.
Starting from the [release version v0.9.6](https://github.com/shalb/cluster.dev/releases/tag/v0.9.6), it is possible to source variables into stack templates directly from `project.yaml`.

## Passing variables across stacks

Cluster.dev allows passing variable values across different stacks within one project. This is made possible in 2 ways:
Expand Down

0 comments on commit a36a6a3

Please sign in to comment.