Update gettings started, add $schema directive at the top of files (#769

)

* Remove invalid references

* Add yaml-language-server

* validate YAML schemas

* try to fix validation

* document editor configuration

* fix FAQ video

* document workaround for complex types

* document how to use JSON with atmos.Component

* reformat as definition list

* adjust css. improve filesystem layout docs

* fix indent

* remove duplicate text

* fix tabs/spaces

* reformat

* clarify documentation relative to example

---------

Co-authored-by: Andriy Knysh <[email protected]>

.github/workflows/test.yml

@@ -329,3 +329,35 @@ jobs:
             --recursive
             --config=${{ github.workspace }}/examples/.tflint.hcl
           fail_on_error: true
+
+  # run other demo tests
+  validate:
+    name: "[validate] ${{ matrix.demo-folder }}"
+    needs: build
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        demo-folder:
+          - demo-context
+          - demo-localstack
+          - demo-stacks
+          - demo-helmfile
+          - quick-start-advanced
+          - quick-start-simple
+
+    timeout-minutes: 20
+    steps:
+      - name: Check out code
+        uses: actions/checkout@v4
+
+      - name: Validate YAML Schema
+        uses: InoUno/[email protected]
+        with:
+          root: "examples/${{ matrix.demo-folder }}/stacks"
+          schemaMapping: |
+            {
+              "https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json": [
+                "examples/${{ matrix.demo-folder }}/stacks/**/*.yaml",
+                "examples/${{ matrix.demo-folder }}/stacks/**/*.yml"
+              ]
+            }

examples/README.md

@@ -1,48 +1,44 @@
 # Examples
 
 > [!TIP]
-  > ### You can try `atmos` directly in your browser using GitHub Codespaces!
-  >
-  > [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=cloudposse/atmos&skip_quickstart=true)
-  >
-  > <i>Already start one? Find it [here](https://github.com/codespaces).</i>
-  >
+> ### You can try `atmos` directly in your browser using GitHub Codespaces!
+>
+> [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=cloudposse/atmos&skip_quickstart=true)
+>
+> <i>Already start one? Find it [here](https://github.com/codespaces).</i>
+>
 
 ## Try it Locally
 
-To play with these demos locally, start by [installing `atmos`](https://atmos.tools/install). 
+To play with these demos locally, start by [installing `atmos`](https://atmos.tools/install).
 
-Then run the following commands (Note, these commands requires that you have `curl` and `tar` installed on your system.)
+Then, clone this repo and [try out the demos](https://github.com/cloudposse/atmos/tree/main/examples).
 
 ```shell
-atmos demo download <example>
-```
+# Clone this repo
+git clone [email protected]:cloudposse/atmos.git
 
-For example, the following command will download the `demo-stacks` example.
-```shell
-atmos demo download demo-stacks
+# Try the examples: https://github.com/cloudposse/atmos/tree/main/examples
+cd examples/
 ```
 
-> [!TIP]
-> #### Fun Fact
->
-> The `download` command is a [custom command](https://atmos.tools/core-concepts/custom-commands) added to the default `atmos.yaml`.
->
-
-
 ## Demos
 
 We designed the demos to be basic examples showcasing functionality. Expect some redundancies and overlap since we reuse examples to demonstrate specific behaviors. Each demo focuses on one area to reduce complexity and make it easier to grasp the concepts.
 
 Think of each demo folder as representing an example of a standalone repository. To make it easier, we put all the demos in one place.
 
 ```shell
-1. ├── demo-stacks/            # Start your journey here
-2. ├── demo-library/           #
-3. ├── demo-validation/        #
-4. ├── demo-vendoring/         #
-5. ├── demo-custom-commands/   #
-6. └── demo-workflows/         #
+1.  ├── demo-stacks/              # Kickstart your journey by exploring stack configurations and their structure.
+2.  ├── demo-library/             # Explore a reusable component library designed for seamless vendoring.
+3.  ├── demo-vendoring/           # Learn how to use vendoring to download and integrate remote dependencies from the `demo-library`.
+4.  ├── demo-validation/          # Validate your configurations to ensure correctness and compliance.
+5.  ├── demo-localstack/          # Leverage LocalStack to provision an S3 bucket using Atmos and Terraform.
+6.  ├── demo-helmfile/            # Deploy NGINX on a local lightweight Kubernetes cluster (k3s) using Helm.
+7.  ├── demo-custom-command/      # Learn how to extend Atmos with your own custom CLI commands.
+8.  ├── demo-component-versions/  # Discover how to manage and use multiple versions of components effectively.
+9.  ├── demo-context/             # Simplify resource naming and tagging with our Terraform context provider.
+10. └── demo-workflows/           # Automate repetitive tasks with streamlined workflows.
 ```
 
 ## Playground

examples/demo-context/stacks/catalog/demo.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 components:
   terraform:
     demo:

examples/demo-context/stacks/deploy/_defaults.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 terraform:
   backend_type: local
 

examples/demo-context/stacks/deploy/dev/demo.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 import:
 - deploy/_defaults
 - catalog/demo

examples/demo-context/stacks/deploy/prod/demo.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 import:
 - deploy/_defaults
 - catalog/demo

examples/demo-context/stacks/deploy/staging/demo.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 import:
 - deploy/_defaults
 - catalog/demo

examples/demo-helmfile/stacks/catalog/demo.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 components:
   helmfile:
     demo:

examples/demo-helmfile/stacks/deploy/dev/demo.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 import:
 - mixins/k3s
 - catalog/demo

examples/demo-helmfile/stacks/deploy/prod/demo.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 import:
 - mixins/k3s
 - catalog/demo

examples/demo-helmfile/stacks/deploy/staging/demo.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 import:
 - mixins/k3s
 - catalog/demo

examples/demo-helmfile/stacks/mixins/k3s.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 env:
   # Configure `kubectl` to use the `kubeconfig.yaml` file generated by the K3s server
   # This needs to be an absolute path, since `helmfile` is executed from the component's directory

examples/demo-localstack/stacks/catalog/demo.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 components:
   terraform:
     demo:

examples/demo-localstack/stacks/deploy/dev/demo.yaml

@@ -1,3 +1,6 @@
+
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 import:
 - mixins/localstack
 - catalog/demo

examples/demo-localstack/stacks/deploy/prod/demo.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 import:
 - mixins/localstack
 - catalog/demo

examples/demo-localstack/stacks/deploy/staging/demo.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 import:
 - mixins/localstack
 - catalog/demo

examples/demo-localstack/stacks/mixins/localstack.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 env:
   # We need to ensure no profile is set when using LocalStack, or the AWS SDK will try to use it
   AWS_PROFILE: ""

examples/demo-stacks/stacks/catalog/myapp.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 components:
   terraform:
     myapp:

examples/demo-stacks/stacks/deploy/dev.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 vars:
   stage: dev
 

examples/demo-stacks/stacks/deploy/prod.yaml

@@ -1,6 +1,8 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 vars:
   stage: prod
-  
+
 import:
   - catalog/myapp
 

examples/demo-stacks/stacks/deploy/staging.yaml

@@ -1,6 +1,8 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 vars:
   stage: staging
-  
+
 import:
   - catalog/myapp
 

examples/demo-workflows/stacks/catalog/myapp.yaml

@@ -0,0 +1 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json

examples/demo-workflows/stacks/deploy/dev.yaml

@@ -0,0 +1 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json

examples/demo-workflows/stacks/deploy/prod.yaml

@@ -0,0 +1 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json

examples/demo-workflows/stacks/deploy/staging.yaml

@@ -0,0 +1 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json

examples/quick-start-simple/stacks/catalog/station.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 components:
   terraform:
     station:

examples/quick-start-simple/stacks/deploy/dev.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 vars:
   stage: dev
 

examples/quick-start-simple/stacks/deploy/prod.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 vars:
   stage: prod
 

examples/quick-start-simple/stacks/deploy/staging.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 vars:
   stage: staging
 

examples/tests/stacks/catalog/helmfile/echo-server.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 components:
   helmfile:
     echo-server:

examples/tests/stacks/catalog/helmfile/infra-server-override.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 components:
   helmfile:
     "infra/infra-server-override":

examples/tests/stacks/catalog/helmfile/infra-server.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 components:
   helmfile:
     "infra/infra-server":

examples/tests/stacks/catalog/invalid-yaml-and-schema/invalid-import-1.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 import:
   - globals/tenant1-globals-does-not-exist
   - catalog/terraform/test-component-does-not-exist

examples/tests/stacks/catalog/invalid-yaml-and-schema/invalid-import-2.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 import:
   # Test invalid import when the file imports itself
   - catalog/invalid-yaml-and-schema/invalid-import-2

examples/tests/stacks/catalog/invalid-yaml-and-schema/invalid-import-3.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 import:
   - [globals/tenant1-globals-invalid]
 

examples/tests/stacks/catalog/invalid-yaml-and-schema/invalid-import-4.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 import:
   globals/tenant1-globals-invalid
 

examples/tests/stacks/catalog/invalid-yaml-and-schema/invalid-import-5.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 import:
   a: globals/tenant1-globals
 

examples/tests/stacks/catalog/invalid-yaml-and-schema/invalid-import-6.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 import: globals/tenant1-globals
 
 vars:

examples/tests/stacks/catalog/invalid-yaml-and-schema/invalid-import-7.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 import:
     -
     - globals/tenant1-globals

examples/tests/stacks/catalog/invalid-yaml-and-schema/invalid-import-8.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 import:
 
 vars:

examples/tests/stacks/catalog/invalid-yaml-and-schema/invalid-import-9.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 import: {}
 
 vars:

examples/tests/stacks/catalog/invalid-yaml-and-schema/invalid-schema-1.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 vars:
 
 terraform:

examples/tests/stacks/catalog/invalid-yaml-and-schema/invalid-schema-10.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 vars:
   stage: invalid
 

examples/tests/stacks/catalog/invalid-yaml-and-schema/invalid-schema-11.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 vars:
   stage: invalid
 

examples/tests/stacks/catalog/invalid-yaml-and-schema/invalid-schema-12.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 vars:
   stage: invalid
 

examples/tests/stacks/catalog/invalid-yaml-and-schema/invalid-schema-13.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 vars:
   stage: invalid
 

examples/tests/stacks/catalog/invalid-yaml-and-schema/invalid-schema-14.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 vars:
   stage: invalid
 

examples/tests/stacks/catalog/invalid-yaml-and-schema/invalid-schema-15.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 vars:
   stage: invalid
 

examples/tests/stacks/catalog/invalid-yaml-and-schema/invalid-schema-2.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 vars:
   stage: invalid
 

examples/tests/stacks/catalog/invalid-yaml-and-schema/invalid-schema-3.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 vars:
   stage: invalid
 

examples/tests/stacks/catalog/invalid-yaml-and-schema/invalid-schema-4.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 vars:
   stage: invalid
 

examples/tests/stacks/catalog/invalid-yaml-and-schema/invalid-schema-5.yaml

@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://atmos.tools/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json
+
 vars:
   stage: invalid