# Deploy with Ansible This guide provides a complete Ansible role for installing and enrolling LinuxGuard. Credentials are encrypted with Ansible Vault so no secrets appear in plaintext in your repository. The role is idempotent — safe to run repeatedly against already-enrolled servers. ## Prerequisites * Ansible 2.9+ or ansible-core 2.12+ installed on the control node * Target hosts reachable via SSH with sudo access * A LinuxGuard API key and tenant ID (from the LinuxGuard console) ## Role Structure The role follows the standard Ansible role directory layout. Create this structure under your `roles/` directory, or generate the skeleton with `ansible-galaxy role init linuxguard`: ``` roles/ └── linuxguard/ ├── defaults/ │ └── main.yml # Default variable values (lowest precedence) ├── handlers/ │ └── main.yml # Handler: restart agent service ├── meta/ │ └── main.yml # Role metadata (galaxy_info, dependencies) └── tasks/ └── main.yml # Core task list ``` ## Encrypting Secrets with Ansible Vault Use `ansible-vault encrypt_string` to encrypt individual values. This approach encrypts the value while keeping the variable name visible in version control, making it easy to audit which variables are vault-protected. Run these commands on your control node and paste the output into `defaults/main.yml`: ```bash ansible-vault encrypt_string '' --name 'linuxguard_api_key' ansible-vault encrypt_string '' --name 'linuxguard_tenant_id' ``` Each command prompts for a vault password and prints an encrypted block. Copy the full output (including the `!vault |` line) into your defaults file as shown in the next section. ## Role Files ### defaults/main.yml ```yaml --- # Values encrypted with: ansible-vault encrypt_string '' --name '' linuxguard_api_key: !vault | $ANSIBLE_VAULT;1.1;AES256 # paste output from encrypt_string here linuxguard_tenant_id: !vault | $ANSIBLE_VAULT;1.1;AES256 # paste output from encrypt_string here ``` ### tasks/main.yml ```yaml --- - name: Install LinuxGuard agent command: > bash -c "curl -fsSL https://packages.linuxguard.io/install-linuxguard.sh | bash -s -- --yes" args: creates: /usr/bin/linuxguard-agent - name: Enable and start LinuxGuard service service: name: linuxguard-agent enabled: true state: started - name: Enroll LinuxGuard agent command: > linuxguard-agent enroll --api-key={{ linuxguard_api_key }} --tenant-id={{ linuxguard_tenant_id }} args: creates: /var/lib/linuxguard/config notify: Restart LinuxGuard agent ``` > **Note:** The `args: creates: /var/lib/linuxguard/config` guard on the enroll task skips enrollment if the agent is already enrolled. See [Automated Deployment Overview](/how-to-guides/how-to/automated-deployment.md) for details on the agent's built-in idempotency behavior. ### handlers/main.yml ```yaml --- - name: Restart LinuxGuard agent service: name: linuxguard-agent state: restarted ``` ### meta/main.yml ```yaml --- galaxy_info: author: your_username description: Install and enroll LinuxGuard agent license: MIT min_ansible_version: "2.9" dependencies: [] ``` ## Running the Role Create a `site.yml` playbook at the root of your project to apply the role to your inventory: ```yaml --- - hosts: all become: true roles: - linuxguard ``` Run the playbook and supply the vault password: ```bash ansible-playbook site.yml --ask-vault-pass # Or with a vault password file: ansible-playbook site.yml --vault-password-file ~/.vault_pass ``` > **Note:** If you use AWX or Ansible Tower, store the vault password as a **Credential** object. The `--ask-vault-pass` flag is not needed — AWX injects the vault password automatically. ## Inline Playbook (Alternative) If you prefer a single-file playbook without a role structure, the equivalent inline form requires no directory layout: ```yaml --- - hosts: all become: true vars: linuxguard_api_key: !vault | $ANSIBLE_VAULT;1.1;AES256 # paste output from encrypt_string here linuxguard_tenant_id: !vault | $ANSIBLE_VAULT;1.1;AES256 # paste output from encrypt_string here tasks: - name: Install LinuxGuard agent command: > bash -c "curl -fsSL https://packages.linuxguard.io/install-linuxguard.sh | bash -s -- --yes" args: creates: /usr/bin/linuxguard-agent - name: Enable and start LinuxGuard service service: name: linuxguard-agent enabled: true state: started - name: Enroll LinuxGuard agent command: > linuxguard-agent enroll --api-key={{ linuxguard_api_key }} --tenant-id={{ linuxguard_tenant_id }} args: creates: /var/lib/linuxguard/config handlers: - name: Restart LinuxGuard agent service: name: linuxguard-agent state: restarted ``` Run the same way: `ansible-playbook site.yml --ask-vault-pass`. ## Verifying the Deployment Add a verification task at the end of `tasks/main.yml` to confirm the agent is running after each playbook run: ```yaml - name: Verify LinuxGuard agent is running service_facts: - name: Assert LinuxGuard agent is active assert: that: "'linuxguard-agent' in services and services['linuxguard-agent'].state == 'running'" fail_msg: "LinuxGuard agent is not running" ``` This task fails the play immediately if the service is not active, surfacing installation or enrollment errors before the run is marked successful. Enrolled servers also appear in the LinuxGuard console under **Infrastructure** within a few minutes of enrollment. *** **Related**: [Automated Deployment Overview](/how-to-guides/how-to/automated-deployment.md) | [Installation](/how-to-guides/how-to/installation.md) | [Configuration](/how-to-guides/how-to/configuration.md) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.linuxguard.io/how-to-guides/how-to/automated-deployment/deploy-with-ansible.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.