hybrid_platforms_conductor 32.12.0 → 32.13.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/CHANGELOG.md +1103 -0
- data/LICENSE.md +31 -0
- data/README.md +395 -0
- data/bin/setup +1 -1
- data/docs/api.md +349 -0
- data/docs/config_dsl.md +315 -0
- data/docs/executables.md +226 -0
- data/docs/executables/check-node.md +155 -0
- data/docs/executables/deploy.md +198 -0
- data/docs/executables/dump_nodes_json.md +110 -0
- data/docs/executables/free_ips.md +93 -0
- data/docs/executables/free_veids.md +73 -0
- data/docs/executables/get_impacted_nodes.md +94 -0
- data/docs/executables/last_deploys.md +114 -0
- data/docs/executables/nodes_to_deploy.md +139 -0
- data/docs/executables/report.md +159 -0
- data/docs/executables/run.md +126 -0
- data/docs/executables/setup.md +92 -0
- data/docs/executables/ssh_config.md +151 -0
- data/docs/executables/test.md +213 -0
- data/docs/executables/topograph.md +139 -0
- data/docs/gen/mermaid/README.md-0.png +0 -0
- data/docs/gen/mermaid/docs/executables/check-node.md-0.png +0 -0
- data/docs/gen/mermaid/docs/executables/deploy.md-0.png +0 -0
- data/docs/gen/mermaid/docs/executables/free_ips.md-0.png +0 -0
- data/docs/gen/mermaid/docs/executables/free_veids.md-0.png +0 -0
- data/docs/gen/mermaid/docs/executables/get_impacted_nodes.md-0.png +0 -0
- data/docs/gen/mermaid/docs/executables/last_deploys.md-0.png +0 -0
- data/docs/gen/mermaid/docs/executables/nodes_to_deploy.md-0.png +0 -0
- data/docs/gen/mermaid/docs/executables/report.md-0.png +0 -0
- data/docs/gen/mermaid/docs/executables/run.md-0.png +0 -0
- data/docs/gen/mermaid/docs/executables/setup.md-0.png +0 -0
- data/docs/gen/mermaid/docs/executables/ssh_config.md-0.png +0 -0
- data/docs/gen/mermaid/docs/executables/test.md-0.png +0 -0
- data/docs/install.md +161 -0
- data/docs/plugins.md +215 -0
- data/docs/plugins/action/bash.md +37 -0
- data/docs/plugins/action/interactive.md +37 -0
- data/docs/plugins/action/remote_bash.md +67 -0
- data/docs/plugins/action/ruby.md +69 -0
- data/docs/plugins/action/scp.md +61 -0
- data/docs/plugins/cmdb/config.md +46 -0
- data/docs/plugins/cmdb/host_ip.md +33 -0
- data/docs/plugins/cmdb/host_keys.md +33 -0
- data/docs/plugins/cmdb/platform_handlers.md +33 -0
- data/docs/plugins/connector/local.md +28 -0
- data/docs/plugins/connector/ssh.md +95 -0
- data/docs/plugins/platform_handler/yaml_inventory.md +105 -0
- data/docs/plugins/provisioner/docker.md +27 -0
- data/docs/plugins/provisioner/podman.md +27 -0
- data/docs/plugins/provisioner/proxmox.md +115 -0
- data/docs/plugins/report/confluence.md +49 -0
- data/docs/plugins/report/mediawiki.md +28 -0
- data/docs/plugins/report/stdout.md +32 -0
- data/docs/plugins/test/bitbucket_conf.md +97 -0
- data/docs/plugins/test/can_be_checked.md +27 -0
- data/docs/plugins/test/check_deploy_and_idempotence.md +61 -0
- data/docs/plugins/test/check_from_scratch.md +28 -0
- data/docs/plugins/test/connection.md +27 -0
- data/docs/plugins/test/deploy_freshness.md +27 -0
- data/docs/plugins/test/deploy_from_scratch.md +28 -0
- data/docs/plugins/test/deploy_removes_root_access.md +29 -0
- data/docs/plugins/test/divergence.md +41 -0
- data/docs/plugins/test/executables.md +26 -0
- data/docs/plugins/test/file_system.md +49 -0
- data/docs/plugins/test/file_system_hdfs.md +65 -0
- data/docs/plugins/test/hostname.md +27 -0
- data/docs/plugins/test/idempotence.md +56 -0
- data/docs/plugins/test/ip.md +28 -0
- data/docs/plugins/test/jenkins_ci_conf.md +54 -0
- data/docs/plugins/test/jenkins_ci_masters_ok.md +54 -0
- data/docs/plugins/test/linear_strategy.md +26 -0
- data/docs/plugins/test/local_users.md +48 -0
- data/docs/plugins/test/mounts.md +55 -0
- data/docs/plugins/test/orphan_files.md +38 -0
- data/docs/plugins/test/ports.md +50 -0
- data/docs/plugins/test/private_ips.md +27 -0
- data/docs/plugins/test/public_ips.md +27 -0
- data/docs/plugins/test/spectre.md +26 -0
- data/docs/plugins/test/veids.md +27 -0
- data/docs/plugins/test/vulnerabilities.md +65 -0
- data/docs/plugins/test_report/confluence.md +43 -0
- data/docs/plugins/test_report/stdout.md +26 -0
- data/docs/plugins_create.md +135 -0
- data/docs/tutorial.md +57 -0
- data/docs/tutorial/01_installation.md +129 -0
- data/docs/tutorial/02_first_node.md +466 -0
- data/docs/tutorial/03_scale.md +876 -0
- data/docs/tutorial/04_test.md +965 -0
- data/docs/tutorial/05_extend_with_plugins.md +1132 -0
- data/examples/bare/Gemfile +4 -0
- data/examples/bare/hpc_config.rb +2 -0
- data/examples/localhost/Gemfile +4 -0
- data/examples/localhost/hpc_config.rb +2 -0
- data/examples/localhost/inventory.yaml +4 -0
- data/lib/hybrid_platforms_conductor/actions_executor.rb +1 -0
- data/lib/hybrid_platforms_conductor/deployer.rb +3 -2
- data/lib/hybrid_platforms_conductor/hpc_plugins/action/remote_bash.rb +29 -13
- data/lib/hybrid_platforms_conductor/hpc_plugins/action/scp.rb +1 -1
- data/lib/hybrid_platforms_conductor/hpc_plugins/connector/local.rb +98 -0
- data/lib/hybrid_platforms_conductor/hpc_plugins/connector/my_connector.rb.sample +2 -2
- data/lib/hybrid_platforms_conductor/hpc_plugins/connector/ssh.rb +7 -3
- data/lib/hybrid_platforms_conductor/hpc_plugins/platform_handler/platform_handler_plugin.rb.sample +5 -5
- data/lib/hybrid_platforms_conductor/hpc_plugins/platform_handler/yaml_inventory.rb +140 -0
- data/lib/hybrid_platforms_conductor/hpc_plugins/provisioner/proxmox.rb +5 -2
- data/lib/hybrid_platforms_conductor/hpc_plugins/test/bitbucket_conf.rb +4 -4
- data/lib/hybrid_platforms_conductor/hpc_plugins/test/deploy_freshness.rb +1 -1
- data/lib/hybrid_platforms_conductor/hpc_plugins/test/deploy_removes_root_access.rb +19 -17
- data/lib/hybrid_platforms_conductor/hpc_plugins/test/divergence.rb +3 -0
- data/lib/hybrid_platforms_conductor/hpc_plugins/test/hostname.rb +2 -1
- data/lib/hybrid_platforms_conductor/hpc_plugins/test/ip.rb +2 -1
- data/lib/hybrid_platforms_conductor/hpc_plugins/test/local_users.rb +2 -1
- data/lib/hybrid_platforms_conductor/hpc_plugins/test/mounts.rb +4 -3
- data/lib/hybrid_platforms_conductor/hpc_plugins/test/orphan_files.rb +2 -1
- data/lib/hybrid_platforms_conductor/hpc_plugins/test/spectre.rb +1 -1
- data/lib/hybrid_platforms_conductor/hpc_plugins/test/vulnerabilities.rb +8 -7
- data/lib/hybrid_platforms_conductor/hpc_plugins/test_report/confluence.rb +1 -1
- data/lib/hybrid_platforms_conductor/json_dumper.rb +1 -1
- data/lib/hybrid_platforms_conductor/platform_handler.rb +1 -1
- data/lib/hybrid_platforms_conductor/services_handler.rb +18 -16
- data/lib/hybrid_platforms_conductor/tests_runner.rb +0 -1
- data/lib/hybrid_platforms_conductor/topographer.rb +0 -1
- data/lib/hybrid_platforms_conductor/version.rb +1 -1
- data/spec/hybrid_platforms_conductor_test/api/actions_executor/actions/remote_bash_spec.rb +16 -0
- data/spec/hybrid_platforms_conductor_test/api/actions_executor/connectors/local/connectable_nodes_spec.rb +30 -0
- data/spec/hybrid_platforms_conductor_test/api/actions_executor/connectors/local/remote_actions_spec.rb +113 -0
- data/spec/hybrid_platforms_conductor_test/api/actions_executor/connectors/ssh/cli_options_spec.rb +6 -2
- data/spec/hybrid_platforms_conductor_test/api/actions_executor/connectors/ssh/global_helpers_spec.rb +38 -1
- data/spec/hybrid_platforms_conductor_test/api/actions_executor/connectors/ssh/remote_actions_spec.rb +8 -8
- data/spec/hybrid_platforms_conductor_test/docs_spec.rb +10 -0
- data/tools/check_md +89 -0
- data/tools/generate_mermaid +75 -0
- metadata +207 -12
@@ -0,0 +1,55 @@
|
|
1
|
+
# Test plugin: `mounts`
|
2
|
+
|
3
|
+
The `mounts` test plugin checks that mounted file systems on nodes are setup correctly.
|
4
|
+
|
5
|
+
## Config DSL extension
|
6
|
+
|
7
|
+
### `check_mounts_do_include`
|
8
|
+
|
9
|
+
Check that a given list of mounts are indeed mounted on a given set of nodes.
|
10
|
+
Takes as parameter a Hash of source => destination mounts to be checked. Each source and destination can be an exact String, or a Regexp for pattern matching.
|
11
|
+
|
12
|
+
Example:
|
13
|
+
```ruby
|
14
|
+
# Make sure our cluster are mounted correctly
|
15
|
+
for_nodes('/datanode-.+/') do
|
16
|
+
check_mounts_do_include(
|
17
|
+
# Local first disk should always be the root one
|
18
|
+
'/dev/sda1' => '/',
|
19
|
+
# Any sdb disk should be mounted somewhere in /mnt
|
20
|
+
/^\/dev\/sdb.+$/ => /^\/mnt\/.*/
|
21
|
+
)
|
22
|
+
end
|
23
|
+
```
|
24
|
+
|
25
|
+
### `check_mounts_do_not_include`
|
26
|
+
|
27
|
+
Check that a given list of mounts are not mounted on a given set of nodes.
|
28
|
+
Takes as parameter a Hash of source => destination mounts to be checked. Each source and destination can be an exact String, or a Regexp for pattern matching.
|
29
|
+
|
30
|
+
Example:
|
31
|
+
```ruby
|
32
|
+
# Make sure our data lake is never mounted on test nodes, in any place
|
33
|
+
for_nodes('/tst.+/') do
|
34
|
+
check_mounts_do_not_include(/^datalake\.my_domain\/com:/ => /.*/)
|
35
|
+
end
|
36
|
+
```
|
37
|
+
|
38
|
+
## Used credentials
|
39
|
+
|
40
|
+
| Credential | Usage
|
41
|
+
| --- | --- |
|
42
|
+
|
43
|
+
## Used Metadata
|
44
|
+
|
45
|
+
| Metadata | Type | Usage
|
46
|
+
| --- | --- | --- |
|
47
|
+
|
48
|
+
## Used environment variables
|
49
|
+
|
50
|
+
| Variable | Usage
|
51
|
+
| --- | --- |
|
52
|
+
|
53
|
+
## External tools dependencies
|
54
|
+
|
55
|
+
None
|
@@ -0,0 +1,38 @@
|
|
1
|
+
# Test plugin: `orphan_files`
|
2
|
+
|
3
|
+
The `orphan_files` test plugin checks that nodes don't have any file belonging to non-existing users or groups.
|
4
|
+
|
5
|
+
## Config DSL extension
|
6
|
+
|
7
|
+
### `ignore_orphan_files_from`
|
8
|
+
|
9
|
+
Give a list of paths to be ignored while checking for orphan files.
|
10
|
+
Useful when some paths are mounted file systems having files belonging to users that are not recognized on some nodes (like remote users).
|
11
|
+
Takes a list of paths (or a single path) as parameter.
|
12
|
+
|
13
|
+
Example:
|
14
|
+
```ruby
|
15
|
+
# Don't check mounted data files
|
16
|
+
for_nodes('/prod.*/') do
|
17
|
+
ignore_orphan_files_from '/datalake'
|
18
|
+
end
|
19
|
+
```
|
20
|
+
|
21
|
+
## Used credentials
|
22
|
+
|
23
|
+
| Credential | Usage
|
24
|
+
| --- | --- |
|
25
|
+
|
26
|
+
## Used Metadata
|
27
|
+
|
28
|
+
| Metadata | Type | Usage
|
29
|
+
| --- | --- | --- |
|
30
|
+
|
31
|
+
## Used environment variables
|
32
|
+
|
33
|
+
| Variable | Usage
|
34
|
+
| --- | --- |
|
35
|
+
|
36
|
+
## External tools dependencies
|
37
|
+
|
38
|
+
None
|
@@ -0,0 +1,50 @@
|
|
1
|
+
# Test plugin: `ports`
|
2
|
+
|
3
|
+
The `ports` test plugin checks that nodes' ports are setup correctly (opened or closed).
|
4
|
+
Useful to check for firewall deployments and general network/security settings.
|
5
|
+
|
6
|
+
## Config DSL extension
|
7
|
+
|
8
|
+
### `check_opened_ports`
|
9
|
+
|
10
|
+
Check that a given list of ports are opened.
|
11
|
+
Takes as parameter a list of (or single) port numbers.
|
12
|
+
|
13
|
+
Example:
|
14
|
+
```ruby
|
15
|
+
# Check that our web services are listing on https
|
16
|
+
for_nodes('/.*web.*/') do
|
17
|
+
check_opened_ports 443
|
18
|
+
end
|
19
|
+
```
|
20
|
+
|
21
|
+
### `check_closed_ports`
|
22
|
+
|
23
|
+
Check that a given list of ports are closed.
|
24
|
+
Takes as parameter a list of (or single) port numbers.
|
25
|
+
|
26
|
+
Example:
|
27
|
+
```ruby
|
28
|
+
# Check that smtp and pop3 are closed on all nodes
|
29
|
+
check_closed_ports 25, 110
|
30
|
+
```
|
31
|
+
|
32
|
+
## Used credentials
|
33
|
+
|
34
|
+
| Credential | Usage
|
35
|
+
| --- | --- |
|
36
|
+
|
37
|
+
## Used Metadata
|
38
|
+
|
39
|
+
| Metadata | Type | Usage
|
40
|
+
| --- | --- | --- |
|
41
|
+
| `host_ip` | `String` | Host IP address to be tested for port listening |
|
42
|
+
|
43
|
+
## Used environment variables
|
44
|
+
|
45
|
+
| Variable | Usage
|
46
|
+
| --- | --- |
|
47
|
+
|
48
|
+
## External tools dependencies
|
49
|
+
|
50
|
+
None
|
@@ -0,0 +1,27 @@
|
|
1
|
+
# Test plugin: `private_ips`
|
2
|
+
|
3
|
+
The `private_ips` test plugin checks that there are no private IP address conflicts among nodes' metadata. The test will fail if at least 2 nodes declare having a common private IP address.
|
4
|
+
|
5
|
+
## Config DSL extension
|
6
|
+
|
7
|
+
None
|
8
|
+
|
9
|
+
## Used credentials
|
10
|
+
|
11
|
+
| Credential | Usage
|
12
|
+
| --- | --- |
|
13
|
+
|
14
|
+
## Used Metadata
|
15
|
+
|
16
|
+
| Metadata | Type | Usage
|
17
|
+
| --- | --- | --- |
|
18
|
+
| `private_ips` | `Array<String>` | List of private IPs to be checked |
|
19
|
+
|
20
|
+
## Used environment variables
|
21
|
+
|
22
|
+
| Variable | Usage
|
23
|
+
| --- | --- |
|
24
|
+
|
25
|
+
## External tools dependencies
|
26
|
+
|
27
|
+
None
|
@@ -0,0 +1,27 @@
|
|
1
|
+
# Test plugin: `public_ips`
|
2
|
+
|
3
|
+
The `public_ips` test plugin checks that there are no public IP address conflicts among nodes' metadata. The test will fail if at least 2 nodes declare having a common public IP address.
|
4
|
+
|
5
|
+
## Config DSL extension
|
6
|
+
|
7
|
+
None
|
8
|
+
|
9
|
+
## Used credentials
|
10
|
+
|
11
|
+
| Credential | Usage
|
12
|
+
| --- | --- |
|
13
|
+
|
14
|
+
## Used Metadata
|
15
|
+
|
16
|
+
| Metadata | Type | Usage
|
17
|
+
| --- | --- | --- |
|
18
|
+
| `public_ips` | `Array<String>` | List of private IPs to be checked |
|
19
|
+
|
20
|
+
## Used environment variables
|
21
|
+
|
22
|
+
| Variable | Usage
|
23
|
+
| --- | --- |
|
24
|
+
|
25
|
+
## External tools dependencies
|
26
|
+
|
27
|
+
None
|
@@ -0,0 +1,26 @@
|
|
1
|
+
# Test plugin: `spectre`
|
2
|
+
|
3
|
+
The `spectre` test plugin checks that nodes are immune to the Spectre variants 1 and 2, and Meltdown vulnerabilities.
|
4
|
+
|
5
|
+
## Config DSL extension
|
6
|
+
|
7
|
+
None
|
8
|
+
|
9
|
+
## Used credentials
|
10
|
+
|
11
|
+
| Credential | Usage
|
12
|
+
| --- | --- |
|
13
|
+
|
14
|
+
## Used Metadata
|
15
|
+
|
16
|
+
| Metadata | Type | Usage
|
17
|
+
| --- | --- | --- |
|
18
|
+
|
19
|
+
## Used environment variables
|
20
|
+
|
21
|
+
| Variable | Usage
|
22
|
+
| --- | --- |
|
23
|
+
|
24
|
+
## External tools dependencies
|
25
|
+
|
26
|
+
None
|
@@ -0,0 +1,27 @@
|
|
1
|
+
# Test plugin: `veids`
|
2
|
+
|
3
|
+
The `veids` test plugin checks that there are no VEID conflicts among nodes' metadata. The test will fail if at least 2 nodes declare having the same VEID.
|
4
|
+
|
5
|
+
## Config DSL extension
|
6
|
+
|
7
|
+
None
|
8
|
+
|
9
|
+
## Used credentials
|
10
|
+
|
11
|
+
| Credential | Usage
|
12
|
+
| --- | --- |
|
13
|
+
|
14
|
+
## Used Metadata
|
15
|
+
|
16
|
+
| Metadata | Type | Usage
|
17
|
+
| --- | --- | --- |
|
18
|
+
| `veid` | `String` or `Integer` | The node's veid |
|
19
|
+
|
20
|
+
## Used environment variables
|
21
|
+
|
22
|
+
| Variable | Usage
|
23
|
+
| --- | --- |
|
24
|
+
|
25
|
+
## External tools dependencies
|
26
|
+
|
27
|
+
None
|
@@ -0,0 +1,65 @@
|
|
1
|
+
# Test plugin: `vulnerabilities`
|
2
|
+
|
3
|
+
The `vulnerabilities` test plugin checks that a node has no known vulnerabilities, as published by its vendor's [OVAL files](https://oval.cisecurity.org/).
|
4
|
+
|
5
|
+
This plugin uses a `oval.json` file storing OVAL files URLs to be fetched, in the image OS directory.
|
6
|
+
Here is the structure of the `oval.json` file:
|
7
|
+
* **repo_urls** (`Array<String>`): List of URLs to fetch OVAL files from. The URL can be:
|
8
|
+
* A direct URL to the OVAL `.xml` file.
|
9
|
+
* A direct URL to a compressed (`.gz` or `.bz2`) OVAL file.
|
10
|
+
* Any other URL that will be then crawled to follow the last link recursively unless it finds a URL to a direct OVAL file (compressed or not). This is useful to give URL of browsable repositories adding OVAL files every day, and always grab the last one.
|
11
|
+
* **reported_severities** (`Array<String>`): List of OVAL item severities to be reported in case nodes are vulnerable to them.
|
12
|
+
|
13
|
+
Example of `oval.json`:
|
14
|
+
```json
|
15
|
+
{
|
16
|
+
"repo_urls": [
|
17
|
+
// Take the most recent OVAL file from our repository
|
18
|
+
"https://my_oval.my_domain.com/oval-definitions"
|
19
|
+
],
|
20
|
+
"reported_severities": [
|
21
|
+
"Critical",
|
22
|
+
"Important",
|
23
|
+
"Unknown"
|
24
|
+
]
|
25
|
+
}
|
26
|
+
```
|
27
|
+
|
28
|
+
Example of `oval.json` for Debian 10:
|
29
|
+
```json
|
30
|
+
{
|
31
|
+
"urls": [
|
32
|
+
// Use directly the published OVAL file from Debian
|
33
|
+
"https://www.debian.org/security/oval/oval-definitions-buster.xml"
|
34
|
+
],
|
35
|
+
"reported_severities": [
|
36
|
+
"Critical",
|
37
|
+
"Important",
|
38
|
+
"Unknown"
|
39
|
+
]
|
40
|
+
}
|
41
|
+
```
|
42
|
+
|
43
|
+
## Config DSL extension
|
44
|
+
|
45
|
+
None
|
46
|
+
|
47
|
+
## Used credentials
|
48
|
+
|
49
|
+
| Credential | Usage
|
50
|
+
| --- | --- |
|
51
|
+
|
52
|
+
## Used Metadata
|
53
|
+
|
54
|
+
| Metadata | Type | Usage
|
55
|
+
| --- | --- | --- |
|
56
|
+
| `image` | `String` | The name of the OS image to be used. The [configuration](../../config_dsl.md) should define the image and point it to a directory containing a `oval.json` that will contain definition of OVAL files to be checked for this OS(see above). |
|
57
|
+
|
58
|
+
## Used environment variables
|
59
|
+
|
60
|
+
| Variable | Usage
|
61
|
+
| --- | --- |
|
62
|
+
|
63
|
+
## External tools dependencies
|
64
|
+
|
65
|
+
None
|
@@ -0,0 +1,43 @@
|
|
1
|
+
# Test Report plugin: `confluence`
|
2
|
+
|
3
|
+
The `confluence` test report plugin is publishing test results in a Confluence page.
|
4
|
+
|
5
|
+
## Config DSL extension
|
6
|
+
|
7
|
+
### `confluence`
|
8
|
+
|
9
|
+
Define a Confluence installation to be targeted.
|
10
|
+
|
11
|
+
It takes the following parameters:
|
12
|
+
* **url** (`String`): URL to the Confluence server
|
13
|
+
* **tests_report_page_id** (`String` or `nil`): Confluence page id used for tests reports, or nil if none [default: nil]
|
14
|
+
|
15
|
+
Example:
|
16
|
+
```ruby
|
17
|
+
# Confluence configuration
|
18
|
+
confluence(
|
19
|
+
url: 'https://my_confluence.my_domain.com/confluence',
|
20
|
+
# Tests report page ID
|
21
|
+
tests_report_page_id: '12345678'
|
22
|
+
)
|
23
|
+
```
|
24
|
+
|
25
|
+
## Used credentials
|
26
|
+
|
27
|
+
| Credential | Usage
|
28
|
+
| --- | --- |
|
29
|
+
| `confluence` | Used to connect to the Confluence API |
|
30
|
+
|
31
|
+
## Used Metadata
|
32
|
+
|
33
|
+
| Metadata | Type | Usage
|
34
|
+
| --- | --- | --- |
|
35
|
+
|
36
|
+
## Used environment variables
|
37
|
+
|
38
|
+
| Variable | Usage
|
39
|
+
| --- | --- |
|
40
|
+
|
41
|
+
## External tools dependencies
|
42
|
+
|
43
|
+
None
|
@@ -0,0 +1,26 @@
|
|
1
|
+
# Test Report plugin: `stdout`
|
2
|
+
|
3
|
+
The `stdout` test report plugin is publishing test results on stdout.
|
4
|
+
|
5
|
+
## Config DSL extension
|
6
|
+
|
7
|
+
None
|
8
|
+
|
9
|
+
## Used credentials
|
10
|
+
|
11
|
+
| Credential | Usage
|
12
|
+
| --- | --- |
|
13
|
+
|
14
|
+
## Used Metadata
|
15
|
+
|
16
|
+
| Metadata | Type | Usage
|
17
|
+
| --- | --- | --- |
|
18
|
+
|
19
|
+
## Used environment variables
|
20
|
+
|
21
|
+
| Variable | Usage
|
22
|
+
| --- | --- |
|
23
|
+
|
24
|
+
## External tools dependencies
|
25
|
+
|
26
|
+
None
|
@@ -0,0 +1,135 @@
|
|
1
|
+
# How to create your own plugins
|
2
|
+
|
3
|
+
This section explains how plugins work in Hybrid Platforms Conductor, and how to extend them by creating your own plugin.
|
4
|
+
|
5
|
+
Plugins are auto-discovered from any Rubygem that is part of a project, by parsing files named `hpc_plugins/<plugin_type>/<plugin_id>.rb`, wherever they are located in the included Rubygem. Those files then declare plugin classes that inherit from the plugin type's base class, named `HybridPlatformsConductor::<PluginType>`.
|
6
|
+
|
7
|
+
Having such simple plugins engine allow projects to adapt their plugins' organization among different repositories or Rubygems the way they see fit.
|
8
|
+
Default plugins are shipped with the `hybrid_platforms_conductor` gem. Check [the plugins' list](./plugins.md) for details.
|
9
|
+
|
10
|
+
Plugins code can use [Hybrid Platforms Conductor's API components](api.md) to use various features and access platforms' information.
|
11
|
+
|
12
|
+
The following sub-sections explain how to install a plugin and the different plugin types that are supported.
|
13
|
+
|
14
|
+
## Example of plugin integration from a repository
|
15
|
+
|
16
|
+
As an example, we will create a test plugin, named `my_hpc_test`, whose code is defined in a Rubygem named `my_hpc_plugin` in another repository.
|
17
|
+
|
18
|
+
### 1. Create the other repository as a Rubygem with your plugin
|
19
|
+
|
20
|
+
```
|
21
|
+
my_hpc_plugin/ (repository root)
|
22
|
+
|-- Gemfile
|
23
|
+
|-- my_hpc_plugin.gemspec
|
24
|
+
`-- lib/
|
25
|
+
`-- my_hpc_plugin/
|
26
|
+
`-- hpc_plugins/
|
27
|
+
`-- test/
|
28
|
+
`-- my_hpc_test.rb
|
29
|
+
```
|
30
|
+
|
31
|
+
#### Gemfile
|
32
|
+
|
33
|
+
The `Gemfile` file should have this simple content:
|
34
|
+
|
35
|
+
```ruby
|
36
|
+
source 'https://rubygems.org'
|
37
|
+
|
38
|
+
gemspec
|
39
|
+
```
|
40
|
+
|
41
|
+
#### my_hpc_plugin.gemspec
|
42
|
+
|
43
|
+
The gemspec file should contain the Rubygem declaration, with all needed dependencies.
|
44
|
+
|
45
|
+
A basic working example of such a file is this:
|
46
|
+
|
47
|
+
```ruby
|
48
|
+
require 'date'
|
49
|
+
|
50
|
+
Gem::Specification.new do |s|
|
51
|
+
s.name = 'my_hpc_plugin'
|
52
|
+
s.version = '0.0.1'
|
53
|
+
s.date = Date.today.to_s
|
54
|
+
s.authors = ['<Your Name>']
|
55
|
+
s.email = ['<your_email>@domain.com']
|
56
|
+
s.summary = 'Plugin for Hybrid Platforms Conductor adding test my_hpc_test'
|
57
|
+
s.description = 'Hybrid Platforms Conductor Plugin to test great things'
|
58
|
+
s.homepage = 'http://my_domain.com'
|
59
|
+
s.license = 'Proprietary'
|
60
|
+
|
61
|
+
s.files = Dir['{bin,lib,spec}/**/*']
|
62
|
+
Dir['bin/**/*'].each do |exec_name|
|
63
|
+
s.executables << File.basename(exec_name)
|
64
|
+
end
|
65
|
+
|
66
|
+
# Dependencies
|
67
|
+
# Add here all the needed Rubygem dependencies for your plugin
|
68
|
+
# s.add_runtime_dependency 'my_awesome_rubygem_lib'
|
69
|
+
end
|
70
|
+
```
|
71
|
+
|
72
|
+
#### lib/my_hpc_plugin/hpc_plugins/test/my_hpc_test.rb
|
73
|
+
|
74
|
+
This file declares the test plugin and implement all the methods that Hybrid Platforms Conductor need to pilot a platform of this type.
|
75
|
+
|
76
|
+
In our example we'll just check a dummy assertion.
|
77
|
+
|
78
|
+
```ruby
|
79
|
+
module MyHpcPlugin
|
80
|
+
|
81
|
+
module HpcPlugins
|
82
|
+
|
83
|
+
module Test
|
84
|
+
|
85
|
+
# Simple test plugin.
|
86
|
+
# Make sure it inherits the correct HybridPlatformsConductor base class.
|
87
|
+
# Make sure this file is in a hpc_plugins/<plugin_type> directory.
|
88
|
+
class MyHpcTest < HybridPlatformsConductor::Test
|
89
|
+
|
90
|
+
# Check my_test_plugin.rb.sample documentation for signature details.
|
91
|
+
def test
|
92
|
+
assert_equal 2 + 2, 4, 'If you see this message you have a serious problem with your CPU'
|
93
|
+
end
|
94
|
+
|
95
|
+
end
|
96
|
+
|
97
|
+
end
|
98
|
+
|
99
|
+
end
|
100
|
+
|
101
|
+
end
|
102
|
+
```
|
103
|
+
|
104
|
+
### 2. Reference this new repository in your application's Gemfile
|
105
|
+
|
106
|
+
This is done in the `Gemfile` of the project that is already using Hybrid Platforms Conductor.
|
107
|
+
|
108
|
+
Adding this line to the file is enough:
|
109
|
+
```ruby
|
110
|
+
gem 'my_hpc_plugin', path: '/path/to/my_hpc_plugin'
|
111
|
+
```
|
112
|
+
|
113
|
+
Later when your Rubygem is part of a Git repository you may change it to:
|
114
|
+
```ruby
|
115
|
+
gem 'my_hpc_plugin', git: '<GIT URL for my_hpc_plugin.git>'
|
116
|
+
```
|
117
|
+
|
118
|
+
Even later when your Rubygem is packaged and deployed as a Rubygem on rubygems.org you may change it to:
|
119
|
+
```ruby
|
120
|
+
gem 'my_hpc_plugin'
|
121
|
+
```
|
122
|
+
|
123
|
+
Once this Gemfile is modified, don't forget to fetch the new dependency:
|
124
|
+
```bash
|
125
|
+
bundle install
|
126
|
+
```
|
127
|
+
In case the plugin is referenced using a local path, there is no need to re-issue `bundle install` when the plugin files change (good to develop locally your plugin).
|
128
|
+
|
129
|
+
### 3. Your plugin is ready to use
|
130
|
+
|
131
|
+
Your test plugin can now be used directly from Hybrid Platforms Conductor.
|
132
|
+
|
133
|
+
```bash
|
134
|
+
./bin/test --test my_hpc_test
|
135
|
+
```
|