> For the complete documentation index, see [llms.txt](https://docs.cloudscript.ai/cloudscript/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cloudscript.ai/cloudscript/syntax/component-modules/service-blocks/configuration.md).

# Configuration

Configuration blocks manage the configuration and setup of your infrastructure resources. Utilizing a playbook-like structure to define tasks that configure servers, install software, manage services, and perform other configuration-related activities. 

## Syntax

```hcl
service "name" {
  configuration {
    play "[play_name]" {
      name    = "[Play Description]"
      hosts   = "[Target Hosts]"
      become  = [true|false]
      vars    = {
        [variable_name] = [value]
      }

      task {
        name    = "[Task Name]"
        [module] {
          [module_specific_attributes]
        }
        [optional_attributes]
      }

      handler {
        name    = "[Handler Name]"
        [module] {
          [module_specific_attributes]
        }
      }
    }
  }
}
```

## Defining Plays

A play groups a set of tasks that are executed against specified hosts. It can include variables, become (privilege escalation), and handlers.

**Attributes:**

* **name**: A descriptive name for the play.
* **hosts**: Specifies the target hosts (e.g., all, specific groups).
* **become**: Determines if privilege escalation is required.
* **vars**: Defines variables to be used within the play.

## Tasks

Tasks define individual actions to configure the system. They use modules to perform specific operations like installing packages, copying files, managing services, etc.

**Common Modules:**

* **package**: Manages software packages.
* **copy**: Copies files to the target system.
* **service**: Manages system services.
* **shell/command**: Executes shell commands.

**Attributes:**

* **name**: A descriptive name for the task.
* **module-specific attributes**: Vary based on the module used.
* **when**: Conditional execution based on system facts.
* **loop**: Iterates over a list of items.
* **register**: Captures the output of a task.
* **notify**: Triggers handlers upon task completion.
* **retries/delay**: Configures retry behavior.

## Handlers

Handlers are special tasks that are triggered by notifications from other tasks. They are typically used to restart or reload services after configuration changes.

**Attributes:**

* **name**: A descriptive name for the handler.
* **module-specific attributes**: Define the action the handler performs.

## Conditionals and Loops

* **when**: Executes tasks based on specific conditions (e.g., OS type).
* **loop**: Repeats tasks for each item in a list.

## Example

```
service "name" {
  configuration {
    play "webapp" {
      name   = "Configure webapp"
      hosts  = "{{ target_servers | default('all') }}"
      become = true
      vars = {
        target_web_servers = "web_servers"
        target_db_servers  = "db_servers"
      }

      task {
        name = "Install required packages"
        package {
          name          = "{{ item }}"
          state         = "present"
          update_cache  = true
        }
        loop = ["nginx", "docker"]
      }

      task {
        name     = "Create/modify /etc/nginx/nginx.conf"
        copy {
          dest    = "/etc/nginx/nginx.conf"
          content = file("nginx.conf")
          mode    = "0644"
          owner   = "root"
          group   = "root"
        }
        notify = ["restart nginx"]
        when   = "ansible_distribution == 'Ubuntu'"
      }

      handler {
        name = "restart nginx"
        service {
          name  = "nginx"
          state = "restarted"
        }
      }
    }
  }
}
```