Scaffold ansible best practices directory structure (ansible#110)

* Initial changes for ansible project scaffolding

* Test fixes

* Add integration test, fixtures, ansible-code-bot.yml file

* Add a check for test_run_init_no_input

* Changes in inventory and other scaffolded files

* Changes in ansible-code-bot.yml file and fixture additions

* Add tests for cli_parser and ruff fixes

* Add README.md

* Modify .prettierignore file

* Add unit test

* Include devcontainer as part of ansible project scaffolding

* Changes in ansible.cfg file

* Add parameters scm-org and scm-project for ansible-project scaffolding

* Replace placeholders in destination path with real values

* Update the content in ansible-navigator.yml and README.md

* Fix site.yml

* Update ansible-core version and requirements.yml

* Make scm_org and scm_project as primary namespace and collection_name for playbook adjacent collection scaffolding

* Add check for scm-org or scm-project absence

* Fix unit tests and add description for scm-org and scm-project params

* Add tests and update fixtures

* Address review changes

* Pre-commit fixes

* Update validation comments in dataclass

* Use global output fixture defined in conftest.py

* Add test for config changes

* Add test for config changes: part2

* review changes

.config/dictionary.txt

@@ -27,6 +27,7 @@ copybutton
 datadir
 datarootdir
 deflist
+devcontainer
 devel
 docsite
 doctree
@@ -83,6 +84,7 @@ mkdocstrings
 moduleauthor
 mqueue              # https://github.com/ansible/ansible-runner/issues/984
 myproject
+myuser
 netcommon           # Ansible network collection, seen in tests and README
 netconf
 nitpicky
@@ -161,6 +163,8 @@ userbase
 viewcode
 volmount
 wantd
+webserver
+webservers
 workdir
 xdist
 xmss

.prettierignore

@@ -1,2 +1,5 @@
 # Stuff we don't want prettier to ever to look into
 tests/fixtures/collection/testorg/testcol/roles/
+tests/fixtures/project/ansible_project/collections/ansible_collections/project_org/project_repo/roles/run/README.md
+tests/fixtures/project/ansible_project/.github/workflows/tests.yml
+tests/fixtures/project/ansible_project/collections/ansible_collections/weather/demo/roles/run/README.md

src/ansible_creator/cli.py

@@ -139,9 +139,35 @@ def parse_args(self: Cli) -> argparse.Namespace:
 
         init_command_parser.add_argument(
             "collection",
+            nargs="?",
             help="The collection name in the format ``<namespace>.<collection>``.",
         )
 
+        init_command_parser.add_argument(
+            "--project",
+            choices=["ansible-project", "collection"],
+            default="collection",
+            help="Project type to scaffold. Valid choices are collection, ansible-project.",
+        )
+
+        init_command_parser.add_argument(
+            "--scm-org",
+            help=(
+                "The SCM org where the ansible-project will be hosted. This value is used as"
+                " the namespace for the playbook adjacent collection."
+                " Required when `--project=ansible-project`."
+            ),
+        )
+
+        init_command_parser.add_argument(
+            "--scm-project",
+            help=(
+                "The SCM project where the ansible-project will be hosted. This value is used as"
+                " the collection_name for the playbook adjacent collection."
+                " Required when `--project=ansible-project`."
+            ),
+        )
+
         init_command_parser.add_argument(
             "--init-path",
             default="./",
@@ -170,7 +196,7 @@ def run(self: Cli) -> None:
             self.output.debug(msg=f"starting requested action '{subcommand}'")
             subcommand = getattr(import_module(subcommand_module), subcommand_cls)
             self.output.debug(f"found action class {subcommand}")
-            subcommand(config=Config(**self.args), output=self.output).run()
+            subcommand(config=Config(**self.args, output=self.output)).run()
         except CreatorError as exc:
             self.output.error(str(exc))
             sys.exit(1)

src/ansible_creator/config.py

@@ -2,29 +2,71 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass, field
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
 
+from ansible_creator.exceptions import CreatorError
 from ansible_creator.utils import expand_path
 
 
+if TYPE_CHECKING:
+    from ansible_creator.output import Output
+
+
 @dataclass(frozen=True)
 class Config:
     """The application configuration for ansible-creator."""
 
     creator_version: str
+    output: Output
     subcommand: str
 
     collection: str = ""
     force: bool = False
     init_path: str = "./"
+    project: str = ""
+    scm_org: str = ""
+    scm_project: str = ""
 
     # TO-DO: Add instance variables for other 'create' and 'sample'
 
-    collection_name: str = field(init=False)
-    namespace: str = field(init=False)
+    collection_name: str = ""
+    namespace: str = ""
 
     def __post_init__(self: Config) -> None:
         """Post process config values."""
+        # Validation for: ansible-creator init
+        if not self.collection and self.project == "collection":
+            msg = "The argument 'collection' is required when scaffolding a collection."
+            raise CreatorError(msg)
+
+        # Validation for: ansible-creator init --project=ansible-project
+        if self.project == "ansible-project" and (
+            self.scm_org is None or self.scm_project is None
+        ):
+            msg = (
+                "Parameters 'scm-org' and 'scm-project' are required when "
+                "scaffolding an ansible-project."
+            )
+            raise CreatorError(msg)
+
+        # Validation for: ansible-creator init testorg.testname --scm-org=weather
+        # --scm-project=demo --project=collection
+        if (self.scm_org or self.scm_project) and self.project != "ansible-project":
+            msg = (
+                "The parameters 'scm-org' and 'scm-project' have no effect when"
+                " project is not set to ansible-project."
+            )
+            self.output.warning(msg)
+
+        # Validation for: ansible-creator init testorg.testname --project=ansible-project
+        # --scm-org weather --scm-project demo
+        if self.collection and self.project != "collection":
+            msg = (
+                "Collection name has no effect when project is set to ansible-project."
+            )
+            self.output.warning(msg)
+
         if self.collection:
             fqcn = self.collection.split(".", maxsplit=1)
             object.__setattr__(self, "namespace", fqcn[0])

src/ansible_creator/resources/ansible_project/.devcontainer/devcontainer.json

@@ -0,0 +1,24 @@
+{
+  "name": "ansible-dev-container-codespaces",
+  "image": "ghcr.io/ansible/community-ansible-dev-tools-container:latest",
+  "containerUser": "podman",
+  "runArgs": [
+    "--security-opt",
+    "seccomp=unconfined",
+    "--security-opt",
+    "label=disable",
+    "--cap-add=SYS_ADMIN",
+    "--cap-add=SYS_RESOURCE",
+    "--device",
+    "/dev/fuse",
+    "--security-opt",
+    "apparmor=unconfined",
+    "--hostname=ansible-dev-container"
+  ],
+  "updateRemoteUserUID": true,
+  "customizations": {
+    "vscode": {
+      "extensions": ["redhat.ansible"]
+    }
+  }
+}

src/ansible_creator/resources/ansible_project/.devcontainer/docker/devcontainer.json

@@ -0,0 +1,24 @@
+{
+  "name": "ansible-dev-container-docker",
+  "image": "ghcr.io/ansible/community-ansible-dev-tools-container:latest",
+  "containerUser": "podman",
+  "runArgs": [
+    "--security-opt",
+    "seccomp=unconfined",
+    "--security-opt",
+    "label=disable",
+    "--cap-add=SYS_ADMIN",
+    "--cap-add=SYS_RESOURCE",
+    "--device",
+    "/dev/fuse",
+    "--security-opt",
+    "apparmor=unconfined",
+    "--hostname=ansible-dev-container"
+  ],
+  "updateRemoteUserUID": true,
+  "customizations": {
+    "vscode": {
+      "extensions": ["redhat.ansible"]
+    }
+  }
+}

src/ansible_creator/resources/ansible_project/.devcontainer/podman/devcontainer.json

@@ -0,0 +1,25 @@
+{
+  "name": "ansible-dev-container-podman",
+  "image": "ghcr.io/ansible/community-ansible-dev-tools-container:latest",
+  "containerUser": "podman",
+  "runArgs": [
+    "--security-opt",
+    "seccomp=unconfined",
+    "--security-opt",
+    "label=disable",
+    "--cap-add=SYS_ADMIN",
+    "--cap-add=SYS_RESOURCE",
+    "--device",
+    "/dev/fuse",
+    "--security-opt",
+    "apparmor=unconfined",
+    "--userns=keep-id:uid=1000,gid=1000",
+    "--hostname=ansible-dev-container"
+  ],
+  "updateRemoteUserUID": true,
+  "customizations": {
+    "vscode": {
+      "extensions": ["redhat.ansible"]
+    }
+  }
+}

src/ansible_creator/resources/ansible_project/.github/ansible-code-bot.yml.j2

@@ -0,0 +1,3 @@
+---
+schedule:
+  interval: "daily"

src/ansible_creator/resources/ansible_project/.github/workflows/tests.yml.j2

@@ -0,0 +1,18 @@
+---
+name: "CI"
+{% raw %}
+concurrency:
+  group: ${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+on:  # yamllint disable-line rule:truthy
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+  schedule:
+    - cron: '0 0 * * *'
+
+jobs:
+  ansible-lint:
+    uses: ansible/ansible-content-actions/.github/workflows/ansible_lint.yaml@main
+{%- endraw %}

src/ansible_creator/resources/ansible_project/.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["redhat.ansible"]
+}

src/ansible_creator/resources/ansible_project/README.md.j2

@@ -0,0 +1,44 @@
+# {{ scm_org|capitalize }} {{ scm_project|capitalize }} Ansible Project
+
+## Included content/ Directory Structure
+
+The directory structure follows best practices recommended by the Ansible community. Feel free to customize this template according to your specific project requirements.
+
+```
+ ansible-project/
+ |── .devcontainer/
+ |    └── docker/
+ |        └── devcontainer.json
+ |    └── podman/
+ |        └── devcontainer.json
+ |    └── devcontainer.json
+ |── .github/
+ |    └── workflows/
+ |        └── tests.yml
+ |    └── ansible-code-bot.yml
+ |── .vscode/
+ |    └── extensions.json
+ |── collections/
+ |   └── requirements.yml
+ |   └── ansible_collections/
+ |       └── project_org/
+ |           └── project_repo/
+ |               └── README.md
+ |               └── roles/sample_role/
+ |                         └── README.md
+ |                         └── tasks/main.yml
+ |── inventory/
+ |   └── groups_vars/
+ |   └── host_vars/
+ |   └── hosts.yml
+ |── ansible-navigator.yml
+ |── ansible.cfg
+ |── linux_playbook.yml
+ |── network_playbook.yml
+ |── README.md
+ |── site.yml
+```
+
+## Compatible with Ansible-lint
+
+Tested with ansible-lint >=24.2.0 releases and the current development version of ansible-core.

src/ansible_creator/resources/ansible_project/ansible-navigator.yml.j2

@@ -0,0 +1,17 @@
+{% raw %}---
+ansible-navigator:
+  logging:
+    level: debug
+    append: False
+    file: $PWD/.logs/ansible-navigator.log
+
+  execution-environment:
+    enabled: true
+    image: ghcr.io/ansible/community-ansible-dev-tools-container:latest
+    pull:
+      policy: always
+
+  playbook-artifact:
+    enable: True
+    save-as: "$PWD/.logs/{playbook_name}-artifact-{time_stamp}.json"
+{%- endraw %}

src/ansible_creator/resources/ansible_project/ansible.cfg.j2

@@ -0,0 +1,26 @@
+[defaults]
+# Specify the inventory file
+inventory = inventory/hosts.yml
+
+# Define the directory for host and group variables
+host_vars_inventory = inventory/host_vars
+group_vars_inventory = inventory/group_vars
+
+# Specify the collections directory
+collections_paths = collections/ansible_collections
+
+# Set the logging verbosity level
+verbosity = 2
+
+# Set the default user for SSH connections
+remote_user = myuser
+
+# Define the default become method
+become_method = sudo
+
+[persistent_connection]
+# Controls how long the persistent connection will remain idle before it is destroyed
+connect_timeout=30
+
+# Controls the amount of time to wait for response from remote device before timing out persistent connection
+command_timeout=30