Ansible Configuration Management user documentation

docs/concepts/resources.md → docs/concepts/resources/README.md

@@ -8,55 +8,55 @@ The Resources view is the result of multiple months of meticulous work understan
 
 This screen shows you the stack-level resources view. By default, resources are shown grouped in a hierarchical manner, grouped by parent. This allows you to see the structure of each of your infrastructure projects:
 
-![](../assets/screenshots/Runs_·_Production_default_worker_pool.png)
+![](../../assets/screenshots/Runs_·_Production_default_worker_pool.png)
 
 Depending on the architecture as well as technology used, your tree may look slightly different - for example, Pulumi trees are generally deeper:
 
-![](<../assets/screenshots/Runs_·_Vendor_Releases_Watcher_and_Slack___checkout-com___Spacelift (1).png>)
+![](<../../assets/screenshots/Runs_·_Vendor_Releases_Watcher_and_Slack___checkout-com___Spacelift (1).png>)
 
 Apart from being grouped by parent, resources can be grouped provider and type. Let's group one of our small stacks by provider:
 
-![](<../assets/screenshots/Runs_·_Spacelift_preproduction_and_Slack___checkout-com___Spacelift (2).png>)
+![](<../../assets/screenshots/Runs_·_Spacelift_preproduction_and_Slack___checkout-com___Spacelift (2).png>)
 
 We can see lots of AWS resources, a few from Stripe, and a lonely one from Datadog. Let's now filter just the Datadog ones, and group them by type:
 
-![](<../assets/screenshots/Runs_·_Spacelift_preproduction_and_Slack_____Paweł_Hytry___Spacelift___1_new_item (3).png>)
+![](<../../assets/screenshots/Runs_·_Spacelift_preproduction_and_Slack_____Paweł_Hytry___Spacelift___1_new_item (3).png>)
 
 Let's now take a look at one of the resources, for example a single `stripe_price`:
 
-![](../assets/screenshots/Runs_·_Spacelift_preproduction.png)
+![](../../assets/screenshots/Runs_·_Spacelift_preproduction.png)
 
 The panel that is now showing on the right hand side of the Resources view shows the details of a single resource, which is now highlighted using a light blue overlay. On this panel, we see two noteworthy things.
 
 Starting with the lower right hand corner, we have the vendor-specific representation of the resource. Note how for security purposes all string values are sanitized. In fact, we never get to see them directly - we only see first 7 characters of their checksum. If you know the possible value, you can easily do the comparison. If you don't, then the secret is safe. As a side note, we do not need to sanitize anything with Pulumi because the team there did an exceptional job with regards to secret management:
 
-![](<../assets/screenshots/Runs_·_Vendor_Releases_Watcher (3).png>)
+![](<../../assets/screenshots/Runs_·_Vendor_Releases_Watcher (3).png>)
 
 More importantly, though, you can drill down to see the runs that either created, or last updated each of the managed resources. Let's now go back to our stripe_price, and click on the ID of the run shown in the _Last updated by_ section. You will notice a little menu pop up:
 
-![](<../assets/screenshots/Runs_·_Spacelift_preproduction (1).png>)
+![](<../../assets/screenshots/Runs_·_Spacelift_preproduction (1).png>)
 
 Clicking on this menu item will take you to the run in question:
 
-![](<../assets/screenshots/Tag_all_Stripe_prices___398__·_Spacelift_preproduction_and_1__local_dev__tmuxinator_start_spacelift (1).png>)
+![](<../../assets/screenshots/Tag_all_Stripe_prices___398__·_Spacelift_preproduction_and_1__local_dev__tmuxinator_start_spacelift (1).png>)
 
 One extra click on the commit SHA will take you to the GitHub commit. Depending on your Git flow, the commit may be linked to a Pull Request, giving you the ultimate visibility into the infrastructure change management process:
 
-![](../assets/screenshots/Tag_all_Stripe_prices___398__·_spacelift-io_infra_57d4958_and_1__local_dev__tmuxinator_start_spacelift.png)
+![](../../assets/screenshots/Tag_all_Stripe_prices___398__·_spacelift-io_infra_57d4958_and_1__local_dev__tmuxinator_start_spacelift.png)
 
 ### Navigating the resource tree
 
 When grouping by resources parent - that is, seeing them as a tree, you can easily click into each subtree, like if you were changing your working directory. You can do this by clicking on the dot representing each node in the tree:
 
-![](../assets/screenshots/Runs_·_Spacelift_development.png)
+![](../../assets/screenshots/Runs_·_Spacelift_development.png)
 
 Once you click into the subtree, you will be able to click out by clicking on the new virtual root, as if you were running `cd ..` in your terminal:
 
-![](<../assets/screenshots/Runs_·_Spacelift_development (1).png>)
+![](<../../assets/screenshots/Runs_·_Spacelift_development (1).png>)
 
 One important aspect about navigating the resource tree is that once you click into the subtree, you are effectively filtering by the ancestor. Which means that grouping and filtering options will now operate on a subset of resources within that subtree:
 
-![](<../assets/screenshots/Runs_·_Spacelift_development (2).png>)
+![](<../../assets/screenshots/Runs_·_Spacelift_development (2).png>)
 
 ## Account-level resources
 
@@ -65,10 +65,10 @@ One important aspect about navigating the resource tree is that once you click i
 
 A view similar to stack-level resources is available for the entire account, too. For this presentation we will use a very _symmetrical_ account - our automated testing instance repeatedly creating and updating the same types of resources in different ways to quickly detect potential regressions:
 
-![](../assets/screenshots/Spacelift.png)
+![](../../assets/screenshots/Spacelift.png)
 
 By default we group by parent, giving you the same hierarchical view as for stack-level resources. But you will notice that there's a new common account root serving as a "virtual" parent for stacks.
 
 In this view you can also filter and group by different properties, with one extra property being the Stack:
 
-![](../assets/screenshots/Spacelift_and_1__local_dev__tmuxinator_start_spacelift.png)
+![](../../assets/screenshots/Spacelift_and_1__local_dev__tmuxinator_start_spacelift.png)

docs/concepts/resources/configuration-management.md

@@ -0,0 +1,58 @@
+# Configuration Management
+
+We’re excited to introduce the **Configuration Management View**, a new feature designed to enhance visibility, control, and monitoring of Ansible tasks across your stacks and runs.
+
+This feature replaces or supplements the existing **Resources View** for Ansible stacks, offering a more focused way to monitor the last status of each item in your Ansible inventory. Below is an overview of the updates and functionality:
+
+## Where You’ll Find It
+
+### Stack View
+
+The Configuration Management View is available in the Stack View, replacing the Resources View for Ansible stacks.
+
+![](../../assets/screenshots/concepts/configuration-management/stack-view.png)
+
+!!! Info
+    Since the new changes replace _Resources View_ you will not be able to see _Resources View_ in Ansible stacks by default. If you'd like to see it (e.g. because you have some historical resources you want to investigate there), you can toggle between the _Configuration Management View_ and the previous _Resources View_ using the “Enable configuration management view” toggle.
+
+### Resources View
+
+The Configuration Management View is also added as a separate tab in the Resources View.
+
+![](../../assets/screenshots/concepts/configuration-management/configuration-management-view.png)
+
+### Run View
+
+The Tasks Tab in the Run View provides detailed visibility into Ansible task execution during a run.
+![](../../assets/screenshots/concepts/configuration-management/run-view.png)
+
+## Key Features
+
+### Task Monitoring
+
+- View the last status of every item in your Ansible inventory, showing the outcome of the most recent run.
+- Navigate seamlessly through tasks to analyze their status, logs, and execution details.
+
+### Enhanced Run List View
+
+- The updated run list now includes Ansible statuses, providing immediate insights without diving into individual runs.
+
+### Detailed Logs in Task Details
+
+Access detailed logs for task execution in the task details tab to diagnose and debug issues efficiently.
+
+## Flexibility and Control
+
+Our integration relies on events generated by Ansible, which can vary based on the playbooks, roles, and plugins used. If you encounter issues with the new Configuration Management View, you can revert to the previous logic by enabling the old flow:
+
+### How to Enable the Old Flow
+
+Add the label: `feature:use_ansible_v1_flow` to your Ansible stack.
+This will restore the _Resources View_ to display Ansible tasks instead of using the new _Configuration Management View_.
+
+## Why Use the Configuration Management View?
+
+- Increase Visibility: Unified workflows for all tools, including Terraform, OpenTofu, and Ansible.
+- Encourage Automation: Seamlessly integrate infrastructure control and configuration management with stack dependencies.
+- Improve Audit Capabilities: Collect, analyze, and filter data from execution logs.
+- Understand Tasks Intuitively: Visualize and filter tasks with ease.

docs/concepts/run/tracked.md

@@ -28,6 +28,19 @@ Runs triggered by individuals and [machine users](../../integrations/api.md#spac
 
 ![](../../assets/screenshots/run/run-started-by-real-and-machine-user.png)
 
+#### Triggering runs with a custom runtime config
+
+It is possible to trigger runs with a custom runtime configuration. This allows you to tailor the runtime environment to specific needs at the moment of triggering a run.
+
+![](../../assets/screenshots/run/trigger-with-custom-runtime-config.png)
+
+The details of runtime config format can be found in the section about [runtime YAML reference](../../concepts/configuration/runtime-configuration/runtime-yaml-reference.md)
+
+![](../../assets/screenshots/run/trigger-custom-runtime-config-details.png)
+
+!!! info
+    Triggering runs with custom runtime config is especially useful when last-mile configuration is needed, for example oftentimes when triggering Ansible runs with custom variables and parameters.
+
 ### Triggering from Git events
 
 Tracked runs can also be triggered by Git push and tag events. By default, whenever a push occurs to the [tracked branch](../stack/stack-settings.md#vcs-integration-and-repository), a tracked run is started - one for each of the affected stacks. This default behavior can be extensively customized using our [push policies](../policy/push-policy/README.md).

docs/concepts/stack/scheduling.md

@@ -34,3 +34,11 @@ Add a schedule with the Task type from the Scheduling section of your stack.
 After creating this schedule, a task will be triggered with the defined command (at a specific timestamp or periodically based on the cron rules defined).
 
 ![](../../assets/screenshots/stack/scheduling/create-task.png)
+
+## Scheduled Run
+
+You can also set up a schedule based on which a tracked run will be created.
+
+![](../../assets/screenshots/stack/scheduling/create-run.png)
+
+Additionally, if you mark **Attach custom runtime config**, you will be able to attach a custom runtime config to the schedule, similarly to when [triggering a run with custom runtime config](../run/tracked.md#triggering-runs-with-a-custom-runtime-config).

docs/vendors/terraform/infracost.md

@@ -109,6 +109,6 @@ warn[sprintf("monthly cost increase greater than %d%% (%.2f%%)", [threshold, per
 
 ### Resources View
 
-Infracost provides information about how individual resources contribute to the overall cost of the stack. Spacelift combines this information with our [resources view](../../concepts/resources.md) to allow you to view the cost information for each resource:
+Infracost provides information about how individual resources contribute to the overall cost of the stack. Spacelift combines this information with our [resources view](../../concepts/resources/README.md) to allow you to view the cost information for each resource:
 
 ![](../../assets/screenshots/3-resources-view.png)

docs/vendors/terraform/resource-sanitization.md

@@ -168,7 +168,7 @@ Smart Sanitization allows you to author [Plan policies](../../concepts/policy/te
     ```
 
 !!! info
-    The same sanitization is also applied to resources shown in the [resources](../../concepts/resources.md) views.
+    The same sanitization is also applied to resources shown in the [resources](../../concepts/resources/README.md) views.
 
 ## Default Sanitization
 

nav.self-hosted.yaml

@@ -44,7 +44,9 @@ nav:
               - concepts/policy/push-policy/run-external-dependencies.md
           - concepts/policy/task-run-policy.md
           - concepts/policy/trigger-policy.md
-      - concepts/resources.md
+      - Resources:
+        - concepts/resources/README.md
+        - concepts/resources/configuration-management.md
       - Worker pools:
           - concepts/worker-pools/README.md
           - concepts/worker-pools/docker-based-workers.md

nav.yaml

@@ -45,7 +45,9 @@ nav:
               - concepts/policy/push-policy/run-external-dependencies.md
           - concepts/policy/task-run-policy.md
           - concepts/policy/trigger-policy.md
-      - concepts/resources.md
+      - Resources:
+        - concepts/resources/README.md
+        - concepts/resources/configuration-management.md
       - Worker pools:
           - concepts/worker-pools/README.md
           - concepts/worker-pools/docker-based-workers.md