Skip to content

Commit 7bf1191

Browse files
syndrsyndr
authored
1.2.1 (#3)
Fix monolith project type Reorganize some documentation
1 parent 69f2dac commit 7bf1191

File tree

4 files changed

+130
-121
lines changed

4 files changed

+130
-121
lines changed

‎README.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ When utilizing an image with systemd support (systemd packages are installed, et
1010

1111
# Using this collection
1212

13+
## Host Requirements
14+
1315
The host from which this collection is run (workstation, CI instance, etc.) must meet the following requirements:
1416

1517
* Molecule [is installed](https://ansible.readthedocs.io/projects/molecule/installation/) and is executable by the user.
@@ -31,6 +33,130 @@ pip install ansible-core
3133

3234
Docker CE can be installed by following the appropriate [installation instructions](https://docs.docker.com/engine/install/) for your OS.
3335

36+
## Project requirements
37+
38+
Roles within this collection will attempt to discover what type of project they are being utilized in. This is enabled by setting the appropriate `project_type` configuration variable to `auto`. The project type can also be explicitly specified if this is desired.
39+
40+
Supported project types:
41+
* `role`
42+
* `collection`
43+
* `monolith`
44+
45+
When used with a role or collection, the Galaxy meta information for the role must be configured!
46+
47+
### Standalone roles
48+
49+
Location: `{{ role_dir }}/meta/main.yml`
50+
51+
For standalone roles that are not part of a collection, the minimum required information is:
52+
```yaml
53+
galaxy_info:
54+
author: you
55+
role_name: cool_stuff
56+
```
57+
58+
It is however strongly recommended that the entire file be updated with the correct information for your role!
59+
60+
### Collections
61+
62+
Location: `{{ collection_dir }}/galaxy.yml`
63+
64+
The following minimum values should be defined:
65+
* `namespace`
66+
* `name`
67+
* `version`
68+
69+
It is however also strongly recommended that the entire file be updated with the correct information for your collection!
70+
71+
### Monoliths
72+
73+
A monolith is a project that contains both roles and playbooks in the same directory structure.
74+
75+
This collection supports the following file structure:
76+
```
77+
.
78+
├── ansible.cfg
79+
├── collections
80+
│   ├── ansible_collections
81+
│   └── requirements.yml
82+
├── inventory
83+
├── molecule
84+
│   └── default
85+
│   ├── [...]
86+
│   ├── collections.yml
87+
│   ├── converge.yml
88+
│   ├── molecule.yml
89+
│   └── verify.yml
90+
├── playbooks
91+
│   ├── configure_toaster
92+
│   │   ├── main.yml -> rick.yml
93+
│   │   ├── README.md
94+
│   │   ├── rick.yml
95+
│   │   ├── tasks
96+
│   │   └── vars
97+
│   ├── configure_server
98+
│   │   ├── main.yml
99+
│   │   ├── README.md
100+
│   │   ├── tasks
101+
│   │   └── templates
102+
│   ├── [...]
103+
│   └── install_things
104+
│   ├── install-cheese.yml
105+
│   ├── tasks
106+
│   └── vars
107+
├── README.md
108+
├── roles
109+
│   ├── powerlevel_9000
110+
│   │   ├── defaults
111+
│   │   ├── meta
112+
│   │   ├── README.md
113+
│   │   ├── tasks
114+
│   │   ├── tests
115+
│   │   └── vars
116+
│   ├── disks
117+
│   │   ├── defaults
118+
│   │   ├── handlers
119+
│   │   ├── meta
120+
│   │   ├── README.md
121+
│   │   ├── tasks
122+
│   │   ├── templates
123+
│   │   ├── tests
124+
│   │   └── vars
125+
│   ├── [...]
126+
│   └── something_else
127+
└── scripts
128+
```
129+
130+
When using this collection within a monolithic repository, make sure that any `ansible.cfg` configuration includes the default ansible locations, or that this collection is installed within the repository.
131+
132+
For example, `ansible.cfg` should contain something like:
133+
```yaml
134+
[defaults]
135+
roles_path = ./roles:/usr/share/ansible/roles:/etc/ansible/roles:~/.ansible/roles
136+
collections_path = ./collections:/usr/share/ansible/collections:~/.ansible/collections
137+
```
138+
139+
or this collection should be installed locally with:
140+
```bash
141+
ansible-galaxy collection install -p ./collections syndr.molecule
142+
```
143+
144+
or if your `collections/requirements.yml` includes this collection:
145+
```bash
146+
ansible-galaxy collection install -p ./collections -r ./collections/requirements.yml
147+
```
148+
149+
#### Testing roles within a monolithic project
150+
151+
When configuring molecule testing for individual roles within a monolithic project (creating a `roles/<role_name>/molecule` directory), take care _not_ to name the scenario "default", as there is already a "default" scenario for the monolithic project itself if you have created `molecule/default` as described above! Instead, name your role scenario with a unique name.
152+
153+
```bash
154+
ROLE_NAME=your_role
155+
mkdir -p molecule/role-$ROLE_NAME
156+
wget -P molecule/role-$ROLE_NAME https://raw.githubusercontent.com/syndr/ansible-collection-molecule/main/roles/init/files/init.yml
157+
ansible-playbook molecule/role-$ROLE_NAME/init.yml
158+
```
159+
34160
# Contributing
35161

36162
Pull requests are welcomed!

‎galaxy.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ namespace: syndr
88
name: molecule
99

1010
# The version of the collection. Must be compatible with semantic versioning
11-
version: 1.2.0
11+
version: 1.2.1
1212

1313
# The path to the Markdown (.md) readme file. This path is relative to the root of the collection
1414
readme: README.md

‎roles/prepare_controller/README.md‎

Lines changed: 1 addition & 117 deletions
Original file line numberDiff line numberDiff line change
@@ -15,123 +15,7 @@ Project formats currently supported by this role are:
1515
* `collection`
1616
* `monolith`
1717

18-
## Galaxy meta configuration
19-
20-
When used with a role or collection, the Galaxy meta information for the role must be configured!
21-
22-
23-
### Standalone roles
24-
25-
Location: `{{ role_dir }}/meta/main.yml`
26-
27-
For standalone roles that are not part of a collection, the minimum required information is:
28-
```yaml
29-
galaxy_info:
30-
author: you
31-
role_name: cool_stuff
32-
```
33-
34-
It is however strongly recommended that the entire file be updated with the correct information for your role!
35-
36-
### Collections
37-
38-
Location: `{{ collection_dir }}/galaxy.yml`
39-
40-
The following minimum values should be defined:
41-
* `namespace`
42-
* `name`
43-
* `version`
44-
45-
It is however also strongly recommended that the entire file be updated with the correct information for your collection!
46-
47-
### Monoliths
48-
49-
A monolith is a project that contains both roles and playbooks in the same directory structure.
50-
51-
This collection supports the following file structure:
52-
```
53-
.
54-
├── ansible.cfg
55-
├── collections
56-
│   ├── ansible_collections
57-
│   └── requirements.yml
58-
├── inventory
59-
├── molecule
60-
│   └── default
61-
│   ├── [...]
62-
│   ├── collections.yml
63-
│   ├── converge.yml
64-
│   ├── molecule.yml
65-
│   └── verify.yml
66-
├── playbooks
67-
│   ├── configure_toaster
68-
│   │   ├── main.yml -> rick.yml
69-
│   │   ├── README.md
70-
│   │   ├── rick.yml
71-
│   │   ├── tasks
72-
│   │   └── vars
73-
│   ├── configure_server
74-
│   │   ├── main.yml
75-
│   │   ├── README.md
76-
│   │   ├── tasks
77-
│   │   └── templates
78-
│   ├── [...]
79-
│   └── install_things
80-
│   ├── install-cheese.yml
81-
│   ├── tasks
82-
│   └── vars
83-
├── README.md
84-
├── roles
85-
│   ├── powerlevel_9000
86-
│   │   ├── defaults
87-
│   │   ├── meta
88-
│   │   ├── README.md
89-
│   │   ├── tasks
90-
│   │   ├── tests
91-
│   │   └── vars
92-
│   ├── disks
93-
│   │   ├── defaults
94-
│   │   ├── handlers
95-
│   │   ├── meta
96-
│   │   ├── README.md
97-
│   │   ├── tasks
98-
│   │   ├── templates
99-
│   │   ├── tests
100-
│   │   └── vars
101-
│   ├── [...]
102-
│   └── something_else
103-
└── scripts
104-
```
105-
106-
When using this collection within a monolithic repository, make sure that any `ansible.cfg` configuration includes the default ansible locations, or that this collection is installed within the repository.
107-
108-
For example, `ansible.cfg` should contain something like:
109-
```yaml
110-
[defaults]
111-
roles_path = ./roles:/usr/share/ansible/roles:/etc/ansible/roles:~/.ansible/roles
112-
collections_path = ./collections:/usr/share/ansible/collections:~/.ansible/collections
113-
```
114-
115-
or this collection should be installed locally with:
116-
```bash
117-
ansible-galaxy collection install -p ./collections syndr.molecule
118-
```
119-
120-
or if your `collections/requirements.yml` includes this collection:
121-
```bash
122-
ansible-galaxy collection install -p ./collections -r ./collections/requirements.yml
123-
```
124-
125-
#### Testing roles within a monolithic project
126-
127-
When configuring molecule testing for individual roles within a monolithic project (creating a `roles/<role_name>/molecule` directory), take care _not_ to name the scenario "default", as there is already a "default" scenario for the monolithic project itself if you have created `molecule/default` as described above! Instead, name your role scenario with a unique name.
128-
129-
```bash
130-
ROLE_NAME=your_role
131-
mkdir -p molecule/role-$ROLE_NAME
132-
wget -P molecule/role-$ROLE_NAME https://raw.githubusercontent.com/syndr/ansible-collection-molecule/main/roles/init/files/init.yml
133-
ansible-playbook molecule/role-$ROLE_NAME/init.yml
134-
```
18+
Specific requirements for each project type can be found in the [collection documentation](../../README.md#project-requirements).
13519

13620
Role Variables
13721
--------------

‎roles/prepare_controller/tasks/monolith.yml‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77

88
- name: Check directory paths
99
ansible.builtin.stat:
10-
path: "{{ __prepare_controller_item }}"
10+
path: "{{ prepare_controller_project_dir }}/{{ __prepare_controller_item }}"
1111
register: __prepare_controller_filepath_stat
1212
loop:
1313
- collections
@@ -21,8 +21,7 @@
2121
that: __prepare_controller_item.stat.exists is true
2222
fail_msg: Required project file layout not found! See README!
2323
success_msg: Path is found
24-
loop: "{{ __prepare_controller_stat.results }}"
24+
loop: "{{ __prepare_controller_filepath_stat.results }}"
2525
loop_control:
2626
loop_var: __prepare_controller_item
27-
label: "{{ __prepare_controller_item.item }}"
2827

0 commit comments

Comments
 (0)