cdk-ansible 0.2.0

# CDK Ansible by Rust

**This project is under construction.**

[![Crates.io][crates-badge]][crates-url]

[crates-badge]: https://img.shields.io/crates/v/cdk-ansible.svg
[crates-url]: https://crates.io/crates/cdk-ansible

`cdk-ansible` is a CDK (Cloud Development Kit) for Ansible, and inspired by AWS CDK.

While Ansible's `playbook` and `inventory` files are written in YAML format, managing YAML templating can be challenging.
`cdk-ansible` enables you to generate Ansible files using **Rust** as a type-safe programming language.

## Features

- [**cdk-ansible**](https://crates.io/crates/cdk-ansible) crate helps you to generate Ansible **Playbook** and **Inventory** files.
- [**cdk-ansible-cli**](https://crates.io/crates/cdk-ansible-cli) (`cdk-ansible` command) generates Rust packages for existing Ansible modules.

## Install Command

### mise

[MISE](https://github.com/jdx/mise) is recommended as it allows you to keep the versions of the cdk-ansible crate and CLI in sync.

```bash
mise use cargo:cdk-ansible-cli
```

### binstall

[binstall](https://crates.io/crates/cargo-binstall)

```bash
cargo binstall cdk-ansible-cli
```

### shell

See [the latest release page](https://github.com/pollenjp/cdk-ansible/releases/latest) and run the command like below.

```sh
# ex) vX.Y.Z
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/pollenjp/cdk-ansible/releases/download/vX.Y.Z/cdk-ansible-cli-installer.sh | sh
```

### cargo install

```bash
cargo install cdk-ansible-cli
```

## Requirements

- cdk-ansible-cli
  - rustfmt
    - `rustup component add rustfmt`

## Usage

### Init cdk-ansible project

Note: (Future feature) `cdk-ansible project` to create a new cdk-ansible's template project.

```text
proj-root/
`-- cdk-ansible/
    `-- Cargo.toml          ... workspace cargo
                                define `workspace.dependencies.cdk-ansible`.
```

### Create Ansible Module package for the workspace

```bash
# specify module name like below.
#
# '<namespace>.<collection>.<module>' only generates the specified module.
cdk-ansible module --output-dir crates/ --module-name ansible.builtin.debug
# '<namespace>.<collection>' generates all modules in the collection.
cdk-ansible module --output-dir crates/ --module-name-regex 'ansible\.builtin\..*'
# '<namespace>' generates all modules in the namespace.
cdk-ansible module --output-dir crates/ --module-name-regex 'ansible\..*'
# If you don't specify `--module-name` or `--module-name-regex`,
# all modules accessible from your ansible environment will be generated.
# (This is the same as `--module-name-regex '*'`)
cdk-ansible module --output-dir crates/

# If you are using uv to manage your ansible project, move to the directory or specify the `--project` option.
uv --project /path/to/your/ansible-project run \
  cdk-ansible module --output-dir crates/ --module-name ansible.builtin.debug
```

```text
proj-root/
`-- cdk-ansible/
  |-- Cargo.toml
  `-- crates/
      `-- cdkam_ansible/  ... auto-generated by `cdk-ansible module` command
          |-- Cargo.toml
          `-- src/
              |-- lib.rs
              |-- m/ansible/builtin/debug.rs
              `-- ...
```

### Define your app

`your-app` project should be like [simple-sample](examples/simple-sample).

```text
proj-root/
`-- cdk-ansible/
  `-- crates/
      |-- cdkam_ansible/
      `-- your-app/       ... Implement `cdk_ansible::Synthesizer` and call `cdk_ansible::run`
```

### Synthesize Ansible files

```bash
cd cdk-ansible
cargo run --package your-app -- synth --output-dir ../ansible
```

```text
proj-root/
|-- cdk-ansible/
`-- ansible/              ... Your ansible project
    |-- inventory/        ... auto-generated by `cdk-ansible synth` command
    |-- playbooks/        ... auto-generated by `cdk-ansible synth` command
    |-- ...
    `-- pyproject.toml
```

Because `synth` subcommand generates 'json' files, **not yaml yet**, you need to convert them to yaml manually.

```bash
cd ansible
find playbooks inventory -name "*.json" \
  | xargs -I{} bash -c \
    'set -eu; \
    filepath_json={}; \
    filepath_yaml="${filepath_json%.json}.yaml"; \
    yq -p json -o yaml "${filepath_json}" > "${filepath_yaml}"'
```