WIP: Document helmfile, template imports

.github/workflows/test.yml

@@ -10,10 +10,10 @@ on:
       - main
       - release/v*
     paths-ignore:
-      - '.github/**'
-      - 'docs/**'
-      - 'examples/**'
-      - 'test/**'
+      - ".github/**"
+      - "docs/**"
+      - "examples/**"
+      - "test/**"
 
   workflow_dispatch:
 
@@ -94,29 +94,29 @@ jobs:
     needs: build
     runs-on: ubuntu-latest
     steps:
-    - name: Check out code
-      uses: actions/checkout@v4
-
-    - uses: hadolint/hadolint-action@v3.1.0
-      id: hadolint
-      with:
-        dockerfile: Dockerfile
-        failure-threshold: warning
-        format: sarif
-        output-file: hadolint.sarif
-        # https://github.com/hadolint/hadolint?tab=readme-ov-file#rules
-        # DL3008 Pin versions in apt-get install
-        ignore: DL3008
-
-    - name: Upload SARIF file
-      uses: github/codeql-action/upload-sarif@v3
-      if: always()
-      with:
-        # Path to SARIF file relative to the root of the repository
-        sarif_file: hadolint.sarif
-        # Optional category for the results (used to differentiate multiple results for one commit)
-        category: hadolint
-        wait-for-processing: true
+      - name: Check out code
+        uses: actions/checkout@v4
+
+      - uses: hadolint/hadolint-action@v3.1.0
+        id: hadolint
+        with:
+          dockerfile: Dockerfile
+          failure-threshold: warning
+          format: sarif
+          output-file: hadolint.sarif
+          # https://github.com/hadolint/hadolint?tab=readme-ov-file#rules
+          # DL3008 Pin versions in apt-get install
+          ignore: DL3008
+
+      - name: Upload SARIF file
+        uses: github/codeql-action/upload-sarif@v3
+        if: always()
+        with:
+          # Path to SARIF file relative to the root of the repository
+          sarif_file: hadolint.sarif
+          # Optional category for the results (used to differentiate multiple results for one commit)
+          category: hadolint
+          wait-for-processing: true
 
   # run localstack demo tests
   localstack:
@@ -254,7 +254,7 @@ jobs:
           # - demo-mock-architecture
           # - demo-stack-templating
           # - demo-multi-cloud
-          # - demo-vendoring
+          - demo-vendoring
 
     timeout-minutes: 20
     steps:

examples/demo-helmfile/atmos.yaml

@@ -7,9 +7,8 @@ schemas:
 components:
   helmfile:
     base_path: "components/helmfile"
+    use_eks: false
     kubeconfig_path: "{{ .Env.KUBECONFIG }}"
-    helm_aws_profile_pattern: default
-    cluster_name_pattern: 'demo'
 
 stacks:
   base_path: "stacks"
@@ -31,10 +30,11 @@ commands:
   description: "Run all tests"
   steps:
   - atmos validate stacks
-  # FIXME: `atmos helmfile apply` assumes EKS
-  #- atmos helmfile apply demo -s dev
-  - atmos helmfile generate varfile demo -s dev
-  - helmfile -f components/helmfile/nginx/helmfile.yaml apply --values dev-demo.helmfile.vars.yaml
+  - atmos helmfile apply demo -s dev
+
+  # This is equivalent to the following commands:
+  #- atmos helmfile generate varfile demo -s dev
+  #- helmfile -f components/helmfile/nginx/helmfile.yaml apply --values dev-demo.helmfile.vars.yaml
 
 # Use Nested Custom Commands to provide easier interface for Docker Compose
 - name: "k3s"

examples/demo-vendoring/atmos.yaml

@@ -7,7 +7,7 @@ components:
     deploy_run_init: true
     init_run_reconfigure: true
     auto_generate_backend_file: false
-  
+
 stacks:
   base_path: "stacks"
   included_paths:
@@ -19,3 +19,12 @@ stacks:
 logs:
   file: "/dev/stderr"
   level: Info
+
+# Custom CLI commands
+
+# No arguments or flags are required
+commands:
+- name: "test"
+  description: "Run all tests"
+  steps:
+  - atmos vendor pull

website/docs/core-concepts/deploy/deploy.mdx

@@ -11,7 +11,6 @@ import Intro from '@site/src/components/Intro';
     Once you're done developing your components and configuring them with stacks, you can deploy them with a single command or in a CI/CD pipeline.
 </Intro>
 
-
 In Atmos, when we talk about "Deployment," it refers to taking the [fully rendered and deep-merged configuration](/core-concepts/describe) of a [stack](/core-concepts/stacks) and provisioning an instance of one of the components. We call this a "component instance," and it's simply a component that has been deployed in a specific stack.
 
 ### Deployment in Atmos
@@ -40,7 +39,6 @@ All configurations in Atmos are defined in YAML. If you can write a Terraform mo
 - [Spacelift](/integrations/spacelift): Our Spacelift integrations support dependency order application.
 - [Atlantis](/integrations/atlantis): By customizing the template generated for Atlantis, similar dependency handling can probably be achieved, although we do not have any documentation on this.
 
-
 ### Automate Cold Starts
 
 Atmos supports [workflows](/core-concepts/workflows), which provide a convenient way to automate deployments, especially for cold starts. A cold start is when you go from zero to a full deployment, typically occurring on day zero in the life cycle of your resources.

website/docs/core-concepts/projects/configuration/helmfile.mdx

@@ -0,0 +1,72 @@
+---
+title: Configure Helmfile
+sidebar_position: 3
+sidebar_label: Configure Helmfile
+id: helmfile
+---
+import Intro from '@site/src/components/Intro'
+import File from '@site/src/components/File'
+
+<Intro>
+Atmos natively supports opinionated workflows for Helmfile. It's compatible with every version of helmfile and designed to work with multiple different versions of Helmfile concurrently.
+</Intro>
+
+Keep in mind that Atmos does not handle the downloading or installation of Helmfile (or its dependency Kustomize); it assumes these commands are already installed on your system. For installation instructions, refer to:
+- [Helmfile Installation Guide](https://helmfile.readthedocs.io/en/latest/#installation)
+- [Kustomize Installation Guide](https://kubectl.docs.kubernetes.io/installation/kustomize/)
+
+To automate the installation process, consider creating a [Custom Command](/core-concepts/custom-commands).
+
+Atmos provides many settings that are specific to Helmfile, which are configured in `atmos.yaml`.
+
+## CLI Configuration
+
+All of the following settings are defined by default in the [Atmos CLI Configuration](/cli/configuration) found in `atmos.yaml`.
+
+:::important
+At this time, these settings cannot be overridden in the [Stack](/core-concepts/stacks/#schema) configuration.
+:::
+
+The defaults for everything are defined underneath the `components.helmfile` section.
+
+```yaml
+components:
+  helmfile:
+    # ...
+```
+
+The following settings are available for Helmfile:
+<dl>
+
+  <dt>`base_path`</dt>
+  <dd>The root directory where the Helmfile components and configurations are located. This path serves as the starting point for resolving any relative paths within the Helmfile setup.</dd>
+
+  <dt>`use_eks` (default: `false`)</dt>
+  <dd>A flag indicating whether the component is configured to use Amazon EKS (Elastic Kubernetes Service). When set to `true`, the component will interact with EKS for provisioning and managing Kubernetes clusters. Also, it means `cluster_name_pattern` must be defined.</dd>
+
+  <dt>`kubeconfig_path`</dt>
+  <dd>The file path to the `kubeconfig` file, which contains the necessary authentication and configuration details to interact with the Kubernetes cluster. This path is essential for managing cluster resources using Helmfile.</dd>
+
+  <dt>`helm_aws_profile_pattern`</dt>
+  <dd>A pattern that defines which AWS CLI profiles should be used by Helm when interacting with AWS services, such as EKS. This allows for dynamic selection of AWS credentials based on the environment or cluster.</dd>
+
+  <dt>`cluster_name_pattern` (required when `use_eks=true`)</dt>
+  <dd>A naming pattern used to identify and select the Kubernetes cluster within the Helmfile configuration. This pattern helps automate the management of different clusters by matching their names based on the specified criteria.</dd>
+
+</dl>
+
+## Example Configuration
+
+Here is an example configuration for Helmfile that we use at Cloud Posse in our [refarch for AWS](https://docs.cloudposse.com/).
+
+<File title="atmos.yaml">
+```yaml
+components:
+  helmfile:
+    base_path: components/helmfile
+    use_eks: true
+    kubeconfig_path: /dev/shm
+    helm_aws_profile_pattern: '{namespace}-{tenant}-gbl-{stage}-helm'
+    cluster_name_pattern: '{namespace}-{tenant}-{environment}-{stage}-eks-cluster'
+```
+</File>

website/docs/core-concepts/stacks/define-components.mdx

@@ -23,11 +23,14 @@ To configure a Component in a [Stack](/core-concepts/stacks), you define the com
   that consists of the resources defined in the `.tf` files in a working directory
   (e.g. [components/terraform/infra/vpc](https://github.com/cloudposse/atmos/tree/main/examples/tests/components/terraform/infra/vpc))
 
-- **Component Configuration** provides configuration (variables and other settings) for a type of component (e.g. a Terraform component) 
+- **Component Configuration** provides configuration (variables and other settings) for a type of component (e.g. a Terraform component)
   and is defined in one or more YAML stack config files (which are called [Atmos stacks](/core-concepts/stacks))
 :::
 
-The schema of an Atmos Component in an Atmos Stack is as follows:
+
+### Terraform Schema
+
+The schema of an Atmos Terraform Component in an Atmos Stack is as follows:
 
 ```yaml
 components:
@@ -39,7 +42,7 @@ components:
       metadata:
         # Components can be of type "real" (default) or "abstract"
         type: real
-        # This is the directory path of the component. 
+        # This is the directory path of the component.
         # In this example, we're referencing a component in the `components/terraform/stable/example` folder.
         component: stable/example
 
@@ -59,10 +62,9 @@ components:
         nodes: 10
 ```
 
-### Component Attributes
+#### Terraform Attributes
 
 <dl>
-
   <dt>`vars` (optional)</dt>
   <dd>The `vars` section is a free-form map. Use [component validation](/core-concepts/validate) to enforce policies.</dd>
 
@@ -134,15 +136,79 @@ components:
 
 </dl>
 
+
+
+### Helmfile Schema
+
+The schema of an Atmos Helmfile Component in an Atmos Stack is as follows:
+
+```yaml
+components:
+  helmfile:
+    # the slug of the component
+    example:
+
+      # configuration specific to atmos
+      metadata:
+        # Components can be of type "real" (default) or "abstract"
+        type: real
+
+        # This is the directory path of the component.
+        # In this example, we're referencing a component in the `components/terraform/stable/example` folder.
+        component: stable/example
+
+        # We can leverage multiple inheritance to sequentially deep merge multiple configurations
+        inherits:
+          - example-defaults
+
+      # Define the Helmfile variables, which will get deep-merged into the Helmfile configuration.
+      vars:
+        enabled: true
+        release_name: my-release
+        chart_version: "1.2.3"
+```
+
+#### Helmfile Attributes
+
+<dl>
+
+  <dt>`vars` (optional)</dt>
+  <dd>The `vars` section is a free-form map. Use [component validation](/core-concepts/validate) to enforce policies.</dd>
+
+  <dt>`vars.namespace` (optional)</dt>
+  <dd>
+  This is an *optional* [`terraform-null-label`](https://github.com/cloudposse/terraform-null-label) convention.
+
+  The namespace of all stacks. Typically, there will be one namespace for the organization.
+
+  Example:
+
+  ```yaml
+  vars:
+    namespace: acme
+  ```
+  </dd>
+
+  <dt>`metadata` (optional)</dt>
+  <dd>The `metadata` section extends functionality of the component.</dd>
+
+  <dt>`settings`</dt>
+  <dd>The `settings` block is a free-form map used to pass configuration information to [integrations](/integrations).</dd>
+
+</dl>
+
+
 ### Types of Components
 
+In Atmos, each component configuration defines its type through the `metadata.type` parameter. This defines how the component behaves—whether it can be used directly to provision resources or serves as a base configuration for other components.
+
 The type of component is expressed in the `metadata.type` parameter of a given component configuration.
 
 There are two types of components:
 <dl>
   <dt>`real`</dt>
-  <dd>is a ["concrete"](https://en.wikipedia.org/wiki/Concrete_class) component instance that can be provisioned</dd>
+  <dd>Think of a `real` component as one that can be deployed. It’s fully configured and ready to be provisioned, similar to a "concrete" class in programming. Once defined, you can use it to create resources or services directly in your infrastructure.</dd>
 
   <dt>`abstract`</dt>
-  <dd>a component configuration, which cannot be instantiated directly. The concept is borrowed from ["abstract base classes"](https://en.wikipedia.org/wiki/Abstract_type) of Object-Oriented Programming</dd>
+  <dd>An `abstract` component is more like a blueprint. It can’t be deployed on its own. Instead, it’s a base configuration that needs to be extended or inherited by other components. This is similar to an ["abstract base classes"](https://en.wikipedia.org/wiki/Abstract_type) in programming—it defines reusable configurations, but it’s not complete enough to be deployed directly.</dd>
 </dl>