From be0d207f902d05d56f75c9cf670791a5d1239e07 Mon Sep 17 00:00:00 2001 From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com> Date: Thu, 15 Jun 2023 19:04:45 +0200 Subject: [PATCH] [PR #6678/c694abbd backport][stable-7] Use semantic markup (modules k-l) (#6703) Use semantic markup (modules k-l) (#6678) * Use semantic markup. * Use option instead of alias. (cherry picked from commit c694abbdf9bd862210c545bbdec24afd596038ae) Co-authored-by: Felix Fontein --- plugins/modules/kdeconfig.py | 8 +- plugins/modules/keycloak_authentication.py | 2 +- .../keycloak_authz_authorization_scope.py | 12 +-- plugins/modules/keycloak_client.py | 101 +++++++++--------- .../modules/keycloak_client_rolemapping.py | 6 +- plugins/modules/keycloak_clientscope.py | 52 ++++----- plugins/modules/keycloak_clientscope_type.py | 2 +- plugins/modules/keycloak_clientsecret_info.py | 6 +- plugins/modules/keycloak_clienttemplate.py | 67 ++++++------ plugins/modules/keycloak_group.py | 10 +- plugins/modules/keycloak_identity_provider.py | 15 +-- plugins/modules/keycloak_realm.py | 4 +- plugins/modules/keycloak_role.py | 4 +- plugins/modules/keycloak_user.py | 6 +- plugins/modules/keycloak_user_federation.py | 49 ++++----- plugins/modules/keycloak_user_rolemapping.py | 8 +- plugins/modules/layman.py | 12 +-- plugins/modules/ldap_attrs.py | 22 ++-- plugins/modules/ldap_entry.py | 12 +-- plugins/modules/ldap_passwd.py | 8 +- plugins/modules/ldap_search.py | 12 +-- plugins/modules/listen_ports_facts.py | 11 +- plugins/modules/lvg.py | 6 +- plugins/modules/lxc_container.py | 20 ++-- plugins/modules/lxd_container.py | 36 +++---- plugins/modules/lxd_project.py | 8 +- 26 files changed, 249 insertions(+), 250 deletions(-) diff --git a/plugins/modules/kdeconfig.py b/plugins/modules/kdeconfig.py index 42a08dd64d..4e8d395215 100644 --- a/plugins/modules/kdeconfig.py +++ b/plugins/modules/kdeconfig.py @@ -35,11 +35,11 @@ options: suboptions: group: description: - - The option's group. One between this and I(groups) is required. + - The option's group. One between this and O(values[].groups) is required. type: str groups: description: - - List of the option's groups. One between this and I(group) is required. + - List of the option's groups. One between this and O(values[].group) is required. type: list elements: str key: @@ -49,12 +49,12 @@ options: required: true value: description: - - The option's value. One between this and I(bool_value) is required. + - The option's value. One between this and O(values[].bool_value) is required. type: str bool_value: description: - Boolean value. - - One between this and I(value) is required. + - One between this and O(values[].value) is required. type: bool required: true backup: diff --git a/plugins/modules/keycloak_authentication.py b/plugins/modules/keycloak_authentication.py index 6143d9d5cd..966d5b20f7 100644 --- a/plugins/modules/keycloak_authentication.py +++ b/plugins/modules/keycloak_authentication.py @@ -97,7 +97,7 @@ options: type: bool default: false description: - - If C(true), allows to remove the authentication flow and recreate it. + - If V(true), allows to remove the authentication flow and recreate it. extends_documentation_fragment: - community.general.keycloak diff --git a/plugins/modules/keycloak_authz_authorization_scope.py b/plugins/modules/keycloak_authz_authorization_scope.py index c451d3751e..5eef9ac765 100644 --- a/plugins/modules/keycloak_authz_authorization_scope.py +++ b/plugins/modules/keycloak_authz_authorization_scope.py @@ -40,8 +40,8 @@ options: state: description: - State of the authorization scope. - - On C(present), the authorization scope will be created (or updated if it exists already). - - On C(absent), the authorization scope will be removed if it exists. + - On V(present), the authorization scope will be created (or updated if it exists already). + - On V(absent), the authorization scope will be removed if it exists. choices: ['present', 'absent'] default: 'present' type: str @@ -108,22 +108,22 @@ end_state: id: description: ID of the authorization scope. type: str - returned: when I(state=present) + returned: when O(state=present) sample: a6ab1cf2-1001-40ec-9f39-48f23b6a0a41 name: description: Name of the authorization scope. type: str - returned: when I(state=present) + returned: when O(state=present) sample: file:delete display_name: description: Display name of the authorization scope. type: str - returned: when I(state=present) + returned: when O(state=present) sample: File delete icon_uri: description: Icon URI for the authorization scope. type: str - returned: when I(state=present) + returned: when O(state=present) sample: http://localhost/icon.png ''' diff --git a/plugins/modules/keycloak_client.py b/plugins/modules/keycloak_client.py index ee687fcb43..6cb0a4ec98 100644 --- a/plugins/modules/keycloak_client.py +++ b/plugins/modules/keycloak_client.py @@ -40,8 +40,8 @@ options: state: description: - State of the client - - On C(present), the client will be created (or updated if it exists already). - - On C(absent), the client will be removed if it exists + - On V(present), the client will be created (or updated if it exists already). + - On V(absent), the client will be removed if it exists choices: ['present', 'absent'] default: 'present' type: str @@ -55,7 +55,7 @@ options: client_id: description: - Client id of client to be worked on. This is usually an alphanumeric name chosen by - you. Either this or I(id) is required. If you specify both, I(id) takes precedence. + you. Either this or O(id) is required. If you specify both, O(id) takes precedence. This is 'clientId' in the Keycloak REST API. aliases: - clientId @@ -63,13 +63,13 @@ options: id: description: - - Id of client to be worked on. This is usually an UUID. Either this or I(client_id) + - Id of client to be worked on. This is usually an UUID. Either this or O(client_id) is required. If you specify both, this takes precedence. type: str name: description: - - Name of the client (this is not the same as I(client_id)). + - Name of the client (this is not the same as O(client_id)). type: str description: @@ -108,12 +108,12 @@ options: client_authenticator_type: description: - - How do clients authenticate with the auth server? Either C(client-secret) or - C(client-jwt) can be chosen. When using C(client-secret), the module parameter - I(secret) can set it, while for C(client-jwt), you can use the keys C(use.jwks.url), - C(jwks.url), and C(jwt.credential.certificate) in the I(attributes) module parameter + - How do clients authenticate with the auth server? Either V(client-secret) or + V(client-jwt) can be chosen. When using V(client-secret), the module parameter + O(secret) can set it, while for V(client-jwt), you can use the keys C(use.jwks.url), + C(jwks.url), and C(jwt.credential.certificate) in the O(attributes) module parameter to configure its behavior. - This is 'clientAuthenticatorType' in the Keycloak REST API. + - This is 'clientAuthenticatorType' in the Keycloak REST API. choices: ['client-secret', 'client-jwt'] aliases: - clientAuthenticatorType @@ -121,7 +121,7 @@ options: secret: description: - - When using I(client_authenticator_type) C(client-secret) (the default), you can + - When using O(client_authenticator_type=client-secret) (the default), you can specify a secret here (otherwise one will be generated if it does not exit). If changing this secret, the module will not register a change currently (but the changed secret will be saved). @@ -246,7 +246,7 @@ options: protocol: description: - - Type of client (either C(openid-connect) or C(saml). + - Type of client. type: str choices: ['openid-connect', 'saml'] @@ -286,7 +286,7 @@ options: use_template_config: description: - - Whether or not to use configuration from the I(client_template). + - Whether or not to use configuration from the O(client_template). This is 'useTemplateConfig' in the Keycloak REST API. aliases: - useTemplateConfig @@ -294,7 +294,7 @@ options: use_template_scope: description: - - Whether or not to use scope configuration from the I(client_template). + - Whether or not to use scope configuration from the O(client_template). This is 'useTemplateScope' in the Keycloak REST API. aliases: - useTemplateScope @@ -302,7 +302,7 @@ options: use_template_mappers: description: - - Whether or not to use mapper configuration from the I(client_template). + - Whether or not to use mapper configuration from the O(client_template). This is 'useTemplateMappers' in the Keycloak REST API. aliases: - useTemplateMappers @@ -391,38 +391,37 @@ options: protocol: description: - - This is either C(openid-connect) or C(saml), this specifies for which protocol this protocol mapper. - is active. + - This specifies for which protocol this protocol mapper is active. choices: ['openid-connect', 'saml'] type: str protocolMapper: description: - - The Keycloak-internal name of the type of this protocol-mapper. While an exhaustive list is + - "The Keycloak-internal name of the type of this protocol-mapper. While an exhaustive list is impossible to provide since this may be extended through SPIs by the user of Keycloak, - by default Keycloak as of 3.4 ships with at least - - C(docker-v2-allow-all-mapper) - - C(oidc-address-mapper) - - C(oidc-full-name-mapper) - - C(oidc-group-membership-mapper) - - C(oidc-hardcoded-claim-mapper) - - C(oidc-hardcoded-role-mapper) - - C(oidc-role-name-mapper) - - C(oidc-script-based-protocol-mapper) - - C(oidc-sha256-pairwise-sub-mapper) - - C(oidc-usermodel-attribute-mapper) - - C(oidc-usermodel-client-role-mapper) - - C(oidc-usermodel-property-mapper) - - C(oidc-usermodel-realm-role-mapper) - - C(oidc-usersessionmodel-note-mapper) - - C(saml-group-membership-mapper) - - C(saml-hardcode-attribute-mapper) - - C(saml-hardcode-role-mapper) - - C(saml-role-list-mapper) - - C(saml-role-name-mapper) - - C(saml-user-attribute-mapper) - - C(saml-user-property-mapper) - - C(saml-user-session-note-mapper) + by default Keycloak as of 3.4 ships with at least:" + - V(docker-v2-allow-all-mapper) + - V(oidc-address-mapper) + - V(oidc-full-name-mapper) + - V(oidc-group-membership-mapper) + - V(oidc-hardcoded-claim-mapper) + - V(oidc-hardcoded-role-mapper) + - V(oidc-role-name-mapper) + - V(oidc-script-based-protocol-mapper) + - V(oidc-sha256-pairwise-sub-mapper) + - V(oidc-usermodel-attribute-mapper) + - V(oidc-usermodel-client-role-mapper) + - V(oidc-usermodel-property-mapper) + - V(oidc-usermodel-realm-role-mapper) + - V(oidc-usersessionmodel-note-mapper) + - V(saml-group-membership-mapper) + - V(saml-hardcode-attribute-mapper) + - V(saml-hardcode-role-mapper) + - V(saml-role-list-mapper) + - V(saml-role-name-mapper) + - V(saml-user-attribute-mapper) + - V(saml-user-property-mapper) + - V(saml-user-session-note-mapper) - An exhaustive list of available mappers on your installation can be obtained on the admin console by going to Server Info -> Providers and looking under 'protocol-mapper'. @@ -431,10 +430,10 @@ options: config: description: - Dict specifying the configuration options for the protocol mapper; the - contents differ depending on the value of I(protocolMapper) and are not documented + contents differ depending on the value of O(protocol_mappers[].protocolMapper) and are not documented other than by the source of the mappers and its parent class(es). An example is given below. It is easiest to obtain valid config values by dumping an already-existing - protocol mapper configuration through check-mode in the I(existing) field. + protocol mapper configuration through check-mode in the RV(existing) field. type: dict attributes: @@ -478,7 +477,7 @@ options: saml.signature.algorithm: description: - - Signature algorithm used to sign SAML documents. One of C(RSA_SHA256), C(RSA_SHA1), C(RSA_SHA512), or C(DSA_SHA1). + - Signature algorithm used to sign SAML documents. One of V(RSA_SHA256), V(RSA_SHA1), V(RSA_SHA512), or V(DSA_SHA1). saml.signing.certificate: description: @@ -503,15 +502,15 @@ options: saml_name_id_format: description: - - For SAML clients, the NameID format to use (one of C(username), C(email), C(transient), or C(persistent)) + - For SAML clients, the NameID format to use (one of V(username), V(email), V(transient), or V(persistent)) saml_signature_canonicalization_method: description: - SAML signature canonicalization method. This is one of four values, namely - C(http://www.w3.org/2001/10/xml-exc-c14n#) for EXCLUSIVE, - C(http://www.w3.org/2001/10/xml-exc-c14n#WithComments) for EXCLUSIVE_WITH_COMMENTS, - C(http://www.w3.org/TR/2001/REC-xml-c14n-20010315) for INCLUSIVE, and - C(http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments) for INCLUSIVE_WITH_COMMENTS. + V(http://www.w3.org/2001/10/xml-exc-c14n#) for EXCLUSIVE, + V(http://www.w3.org/2001/10/xml-exc-c14n#WithComments) for EXCLUSIVE_WITH_COMMENTS, + V(http://www.w3.org/TR/2001/REC-xml-c14n-20010315) for INCLUSIVE, and + V(http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments) for INCLUSIVE_WITH_COMMENTS. saml_single_logout_service_url_post: description: @@ -523,12 +522,12 @@ options: user.info.response.signature.alg: description: - - For OpenID-Connect clients, JWA algorithm for signed UserInfo-endpoint responses. One of C(RS256) or C(unsigned). + - For OpenID-Connect clients, JWA algorithm for signed UserInfo-endpoint responses. One of V(RS256) or V(unsigned). request.object.signature.alg: description: - For OpenID-Connect clients, JWA algorithm which the client needs to use when sending - OIDC request object. One of C(any), C(none), C(RS256). + OIDC request object. One of V(any), V(none), V(RS256). use.jwks.url: description: diff --git a/plugins/modules/keycloak_client_rolemapping.py b/plugins/modules/keycloak_client_rolemapping.py index 57dcac48de..420ed9c1f5 100644 --- a/plugins/modules/keycloak_client_rolemapping.py +++ b/plugins/modules/keycloak_client_rolemapping.py @@ -43,8 +43,8 @@ options: state: description: - State of the client_rolemapping. - - On C(present), the client_rolemapping will be created if it does not yet exist, or updated with the parameters you provide. - - On C(absent), the client_rolemapping will be removed if it exists. + - On V(present), the client_rolemapping will be created if it does not yet exist, or updated with the parameters you provide. + - On V(absent), the client_rolemapping will be removed if it exists. default: 'present' type: str choices: @@ -73,7 +73,7 @@ options: client_id: type: str description: - - Name of the client to be mapped (different than I(cid)). + - Name of the client to be mapped (different than O(cid)). - This parameter is required (can be replaced by cid for less API call). cid: diff --git a/plugins/modules/keycloak_clientscope.py b/plugins/modules/keycloak_clientscope.py index a23d92867a..d37af5f0cf 100644 --- a/plugins/modules/keycloak_clientscope.py +++ b/plugins/modules/keycloak_clientscope.py @@ -43,8 +43,8 @@ options: state: description: - State of the client_scope. - - On C(present), the client_scope will be created if it does not yet exist, or updated with the parameters you provide. - - On C(absent), the client_scope will be removed if it exists. + - On V(present), the client_scope will be created if it does not yet exist, or updated with the parameters you provide. + - On V(absent), the client_scope will be removed if it exists. default: 'present' type: str choices: @@ -103,28 +103,28 @@ options: - "The Keycloak-internal name of the type of this protocol-mapper. While an exhaustive list is impossible to provide since this may be extended through SPIs by the user of Keycloak, by default Keycloak as of 3.4 ships with at least:" - - C(docker-v2-allow-all-mapper) - - C(oidc-address-mapper) - - C(oidc-full-name-mapper) - - C(oidc-group-membership-mapper) - - C(oidc-hardcoded-claim-mapper) - - C(oidc-hardcoded-role-mapper) - - C(oidc-role-name-mapper) - - C(oidc-script-based-protocol-mapper) - - C(oidc-sha256-pairwise-sub-mapper) - - C(oidc-usermodel-attribute-mapper) - - C(oidc-usermodel-client-role-mapper) - - C(oidc-usermodel-property-mapper) - - C(oidc-usermodel-realm-role-mapper) - - C(oidc-usersessionmodel-note-mapper) - - C(saml-group-membership-mapper) - - C(saml-hardcode-attribute-mapper) - - C(saml-hardcode-role-mapper) - - C(saml-role-list-mapper) - - C(saml-role-name-mapper) - - C(saml-user-attribute-mapper) - - C(saml-user-property-mapper) - - C(saml-user-session-note-mapper) + - V(docker-v2-allow-all-mapper) + - V(oidc-address-mapper) + - V(oidc-full-name-mapper) + - V(oidc-group-membership-mapper) + - V(oidc-hardcoded-claim-mapper) + - V(oidc-hardcoded-role-mapper) + - V(oidc-role-name-mapper) + - V(oidc-script-based-protocol-mapper) + - V(oidc-sha256-pairwise-sub-mapper) + - V(oidc-usermodel-attribute-mapper) + - V(oidc-usermodel-client-role-mapper) + - V(oidc-usermodel-property-mapper) + - V(oidc-usermodel-realm-role-mapper) + - V(oidc-usersessionmodel-note-mapper) + - V(saml-group-membership-mapper) + - V(saml-hardcode-attribute-mapper) + - V(saml-hardcode-role-mapper) + - V(saml-role-list-mapper) + - V(saml-role-name-mapper) + - V(saml-user-attribute-mapper) + - V(saml-user-property-mapper) + - V(saml-user-session-note-mapper) - An exhaustive list of available mappers on your installation can be obtained on the admin console by going to Server Info -> Providers and looking under 'protocol-mapper'. @@ -143,10 +143,10 @@ options: config: description: - Dict specifying the configuration options for the protocol mapper; the - contents differ depending on the value of I(protocolMapper) and are not documented + contents differ depending on the value of O(protocol_mappers[].protocolMapper) and are not documented other than by the source of the mappers and its parent class(es). An example is given below. It is easiest to obtain valid config values by dumping an already-existing - protocol mapper configuration through check-mode in the C(existing) return value. + protocol mapper configuration through check-mode in the RV(existing) return value. type: dict attributes: diff --git a/plugins/modules/keycloak_clientscope_type.py b/plugins/modules/keycloak_clientscope_type.py index facf02aa47..0165b1abe8 100644 --- a/plugins/modules/keycloak_clientscope_type.py +++ b/plugins/modules/keycloak_clientscope_type.py @@ -40,7 +40,7 @@ options: client_id: description: - - The I(client_id) of the client. If not set the clientscop types are set as a default for the realm. + - The O(client_id) of the client. If not set the clientscop types are set as a default for the realm. aliases: - clientId type: str diff --git a/plugins/modules/keycloak_clientsecret_info.py b/plugins/modules/keycloak_clientsecret_info.py index 98a41ad20a..c772620351 100644 --- a/plugins/modules/keycloak_clientsecret_info.py +++ b/plugins/modules/keycloak_clientsecret_info.py @@ -26,8 +26,8 @@ description: and a user having the expected roles. - When retrieving a new client secret, where possible provide the client's - I(id) (not I(client_id)) to the module. This removes a lookup to the API to - translate the I(client_id) into the client ID. + O(id) (not O(client_id)) to the module. This removes a lookup to the API to + translate the O(client_id) into the client ID. - "Note that this module returns the client secret. To avoid this showing up in the logs, please add C(no_log: true) to the task." @@ -48,7 +48,7 @@ options: client_id: description: - - The I(client_id) of the client. Passing this instead of I(id) results in an + - The O(client_id) of the client. Passing this instead of O(id) results in an extra API call. aliases: - clientId diff --git a/plugins/modules/keycloak_clienttemplate.py b/plugins/modules/keycloak_clienttemplate.py index d2555afc5b..cd7f6c09b7 100644 --- a/plugins/modules/keycloak_clienttemplate.py +++ b/plugins/modules/keycloak_clienttemplate.py @@ -38,8 +38,8 @@ options: state: description: - State of the client template. - - On C(present), the client template will be created (or updated if it exists already). - - On C(absent), the client template will be removed if it exists + - On V(present), the client template will be created (or updated if it exists already). + - On V(absent), the client template will be removed if it exists choices: ['present', 'absent'] default: 'present' type: str @@ -67,7 +67,7 @@ options: protocol: description: - - Type of client template (either C(openid-connect) or C(saml). + - Type of client template. choices: ['openid-connect', 'saml'] type: str @@ -106,38 +106,37 @@ options: protocol: description: - - This is either C(openid-connect) or C(saml), this specifies for which protocol this protocol mapper. - is active. + - This specifies for which protocol this protocol mapper is active. choices: ['openid-connect', 'saml'] type: str protocolMapper: description: - - The Keycloak-internal name of the type of this protocol-mapper. While an exhaustive list is + - "The Keycloak-internal name of the type of this protocol-mapper. While an exhaustive list is impossible to provide since this may be extended through SPIs by the user of Keycloak, - by default Keycloak as of 3.4 ships with at least - - C(docker-v2-allow-all-mapper) - - C(oidc-address-mapper) - - C(oidc-full-name-mapper) - - C(oidc-group-membership-mapper) - - C(oidc-hardcoded-claim-mapper) - - C(oidc-hardcoded-role-mapper) - - C(oidc-role-name-mapper) - - C(oidc-script-based-protocol-mapper) - - C(oidc-sha256-pairwise-sub-mapper) - - C(oidc-usermodel-attribute-mapper) - - C(oidc-usermodel-client-role-mapper) - - C(oidc-usermodel-property-mapper) - - C(oidc-usermodel-realm-role-mapper) - - C(oidc-usersessionmodel-note-mapper) - - C(saml-group-membership-mapper) - - C(saml-hardcode-attribute-mapper) - - C(saml-hardcode-role-mapper) - - C(saml-role-list-mapper) - - C(saml-role-name-mapper) - - C(saml-user-attribute-mapper) - - C(saml-user-property-mapper) - - C(saml-user-session-note-mapper) + by default Keycloak as of 3.4 ships with at least:" + - V(docker-v2-allow-all-mapper) + - V(oidc-address-mapper) + - V(oidc-full-name-mapper) + - V(oidc-group-membership-mapper) + - V(oidc-hardcoded-claim-mapper) + - V(oidc-hardcoded-role-mapper) + - V(oidc-role-name-mapper) + - V(oidc-script-based-protocol-mapper) + - V(oidc-sha256-pairwise-sub-mapper) + - V(oidc-usermodel-attribute-mapper) + - V(oidc-usermodel-client-role-mapper) + - V(oidc-usermodel-property-mapper) + - V(oidc-usermodel-realm-role-mapper) + - V(oidc-usersessionmodel-note-mapper) + - V(saml-group-membership-mapper) + - V(saml-hardcode-attribute-mapper) + - V(saml-hardcode-role-mapper) + - V(saml-role-list-mapper) + - V(saml-role-name-mapper) + - V(saml-user-attribute-mapper) + - V(saml-user-property-mapper) + - V(saml-user-session-note-mapper) - An exhaustive list of available mappers on your installation can be obtained on the admin console by going to Server Info -> Providers and looking under 'protocol-mapper'. @@ -146,10 +145,10 @@ options: config: description: - Dict specifying the configuration options for the protocol mapper; the - contents differ depending on the value of I(protocolMapper) and are not documented + contents differ depending on the value of O(protocol_mappers[].protocolMapper) and are not documented other than by the source of the mappers and its parent class(es). An example is given below. It is easiest to obtain valid config values by dumping an already-existing - protocol mapper configuration through check-mode in the I(existing) field. + protocol mapper configuration through check-mode in the RV(existing) field. type: dict attributes: @@ -160,9 +159,9 @@ options: type: dict notes: - - The Keycloak REST API defines further fields (namely I(bearerOnly), I(consentRequired), I(standardFlowEnabled), - I(implicitFlowEnabled), I(directAccessGrantsEnabled), I(serviceAccountsEnabled), I(publicClient), and - I(frontchannelLogout)) which, while available with keycloak_client, do not have any effect on + - The Keycloak REST API defines further fields (namely C(bearerOnly), C(consentRequired), C(standardFlowEnabled), + C(implicitFlowEnabled), C(directAccessGrantsEnabled), C(serviceAccountsEnabled), C(publicClient), and + C(frontchannelLogout)) which, while available with keycloak_client, do not have any effect on Keycloak client-templates and are discarded if supplied with an API request changing client-templates. As such, they are not available through this module. diff --git a/plugins/modules/keycloak_group.py b/plugins/modules/keycloak_group.py index 399bc5b4fa..5398a4b5d0 100644 --- a/plugins/modules/keycloak_group.py +++ b/plugins/modules/keycloak_group.py @@ -41,9 +41,9 @@ options: state: description: - State of the group. - - On C(present), the group will be created if it does not yet exist, or updated with the parameters you provide. + - On V(present), the group will be created if it does not yet exist, or updated with the parameters you provide. - >- - On C(absent), the group will be removed if it exists. Be aware that absenting + On V(absent), the group will be removed if it exists. Be aware that absenting a group with subgroups will automatically delete all its subgroups too. default: 'present' type: str @@ -93,7 +93,7 @@ options: type: str description: - Identify parent by ID. - - Needs less API calls than using I(name). + - Needs less API calls than using O(parents[].name). - A deep parent chain can be started at any point when first given parent is given as ID. - Note that in principle both ID and name can be specified at the same time but current implementation only always use just one of them, with ID @@ -102,14 +102,14 @@ options: type: str description: - Identify parent by name. - - Needs more internal API calls than using I(id) to map names to ID's under the hood. + - Needs more internal API calls than using O(parents[].id) to map names to ID's under the hood. - When giving a parent chain with only names it must be complete up to the top. - Note that in principle both ID and name can be specified at the same time but current implementation only always use just one of them, with ID being preferred. notes: - - Presently, the I(realmRoles), I(clientRoles) and I(access) attributes returned by the Keycloak API + - Presently, the RV(end_state.realmRoles), RV(end_state.clientRoles), and RV(end_state.access) attributes returned by the Keycloak API are read-only for groups. This limitation will be removed in a later version of this module. extends_documentation_fragment: diff --git a/plugins/modules/keycloak_identity_provider.py b/plugins/modules/keycloak_identity_provider.py index 0d12ae03a4..a135b16e43 100644 --- a/plugins/modules/keycloak_identity_provider.py +++ b/plugins/modules/keycloak_identity_provider.py @@ -36,8 +36,8 @@ options: state: description: - State of the identity provider. - - On C(present), the identity provider will be created if it does not yet exist, or updated with the parameters you provide. - - On C(absent), the identity provider will be removed if it exists. + - On V(present), the identity provider will be created if it does not yet exist, or updated with the parameters you provide. + - On V(absent), the identity provider will be removed if it exists. default: 'present' type: str choices: @@ -120,16 +120,16 @@ options: provider_id: description: - - Protocol used by this provider (supported values are C(oidc) or C(saml)). + - Protocol used by this provider (supported values are V(oidc) or V(saml)). aliases: - providerId type: str config: description: - - Dict specifying the configuration options for the provider; the contents differ depending on the value of I(providerId). - Examples are given below for C(oidc) and C(saml). It is easiest to obtain valid config values by dumping an already-existing - identity provider configuration through check-mode in the I(existing) field. + - Dict specifying the configuration options for the provider; the contents differ depending on the value of O(provider_id). + Examples are given below for V(oidc) and V(saml). It is easiest to obtain valid config values by dumping an already-existing + identity provider configuration through check-mode in the RV(existing) field. type: dict suboptions: hide_on_login_page: @@ -271,7 +271,8 @@ options: config: description: - - Dict specifying the configuration options for the mapper; the contents differ depending on the value of I(identityProviderMapper). + - Dict specifying the configuration options for the mapper; the contents differ depending on the value of + O(mappers[].identityProviderMapper). type: dict extends_documentation_fragment: diff --git a/plugins/modules/keycloak_realm.py b/plugins/modules/keycloak_realm.py index 53f81be489..9f2e72b525 100644 --- a/plugins/modules/keycloak_realm.py +++ b/plugins/modules/keycloak_realm.py @@ -42,8 +42,8 @@ options: state: description: - State of the realm. - - On C(present), the realm will be created (or updated if it exists already). - - On C(absent), the realm will be removed if it exists. + - On V(present), the realm will be created (or updated if it exists already). + - On V(absent), the realm will be removed if it exists. choices: ['present', 'absent'] default: 'present' type: str diff --git a/plugins/modules/keycloak_role.py b/plugins/modules/keycloak_role.py index 46758a7621..f3e01483f8 100644 --- a/plugins/modules/keycloak_role.py +++ b/plugins/modules/keycloak_role.py @@ -40,8 +40,8 @@ options: state: description: - State of the role. - - On C(present), the role will be created if it does not yet exist, or updated with the parameters you provide. - - On C(absent), the role will be removed if it exists. + - On V(present), the role will be created if it does not yet exist, or updated with the parameters you provide. + - On V(absent), the role will be removed if it exists. default: 'present' type: str choices: diff --git a/plugins/modules/keycloak_user.py b/plugins/modules/keycloak_user.py index b6d2bfa747..61be26e5e2 100644 --- a/plugins/modules/keycloak_user.py +++ b/plugins/modules/keycloak_user.py @@ -135,7 +135,7 @@ options: required: true temporary: description: - - If C(true), the users are required to reset their credentials at next login. + - If V(true), the users are required to reset their credentials at next login. type: bool default: false required_actions: @@ -207,7 +207,7 @@ options: type: str force: description: - - If C(true), allows to remove user and recreate it. + - If V(true), allows to remove user and recreate it. type: bool default: false extends_documentation_fragment: @@ -345,7 +345,7 @@ end_state: returned: on success type: dict changed: - description: Return C(true) if the operation changed the user on the keycloak server, C(false) otherwise. + description: Return V(true) if the operation changed the user on the keycloak server, V(false) otherwise. returned: always type: bool ''' diff --git a/plugins/modules/keycloak_user_federation.py b/plugins/modules/keycloak_user_federation.py index c0dc5d271b..b29cf21859 100644 --- a/plugins/modules/keycloak_user_federation.py +++ b/plugins/modules/keycloak_user_federation.py @@ -36,9 +36,9 @@ options: state: description: - State of the user federation. - - On C(present), the user federation will be created if it does not yet exist, or updated with + - On V(present), the user federation will be created if it does not yet exist, or updated with the parameters you provide. - - On C(absent), the user federation will be removed if it exists. + - On V(absent), the user federation will be removed if it exists. default: 'present' type: str choices: @@ -54,7 +54,7 @@ options: id: description: - The unique ID for this user federation. If left empty, the user federation will be searched - by its I(name). + by its O(name). type: str name: @@ -75,7 +75,7 @@ options: provider_type: description: - - Component type for user federation (only supported value is C(org.keycloak.storage.UserStorageProvider)). + - Component type for user federation (only supported value is V(org.keycloak.storage.UserStorageProvider)). aliases: - providerType default: org.keycloak.storage.UserStorageProvider @@ -91,10 +91,10 @@ options: config: description: - Dict specifying the configuration options for the provider; the contents differ depending on - the value of I(provider_id). Examples are given below for C(ldap), C(kerberos) and C(sssd). + the value of O(provider_id). Examples are given below for V(ldap), V(kerberos) and V(sssd). It is easiest to obtain valid config values by dumping an already-existing user federation - configuration through check-mode in the I(existing) field. - - The value C(sssd) has been supported since community.general 4.2.0. + configuration through check-mode in the RV(existing) field. + - The value V(sssd) has been supported since community.general 4.2.0. type: dict suboptions: enabled: @@ -111,15 +111,15 @@ options: importEnabled: description: - - If C(true), LDAP users will be imported into Keycloak DB and synced by the configured + - If V(true), LDAP users will be imported into Keycloak DB and synced by the configured sync policies. default: true type: bool editMode: description: - - C(READ_ONLY) is a read-only LDAP store. C(WRITABLE) means data will be synced back to LDAP - on demand. C(UNSYNCED) means user data will be imported, but not synced back to LDAP. + - V(READ_ONLY) is a read-only LDAP store. V(WRITABLE) means data will be synced back to LDAP + on demand. V(UNSYNCED) means user data will be imported, but not synced back to LDAP. type: str choices: - READ_ONLY @@ -136,13 +136,13 @@ options: vendor: description: - LDAP vendor (provider). - - Use short name. For instance, write C(rhds) for "Red Hat Directory Server". + - Use short name. For instance, write V(rhds) for "Red Hat Directory Server". type: str usernameLDAPAttribute: description: - Name of LDAP attribute, which is mapped as Keycloak username. For many LDAP server - vendors it can be C(uid). For Active directory it can be C(sAMAccountName) or C(cn). + vendors it can be V(uid). For Active directory it can be V(sAMAccountName) or V(cn). The attribute should be filled for all LDAP user records you want to import from LDAP to Keycloak. type: str @@ -151,15 +151,15 @@ options: description: - Name of LDAP attribute, which is used as RDN (top attribute) of typical user DN. Usually it's the same as Username LDAP attribute, however it is not required. For - example for Active directory, it is common to use C(cn) as RDN attribute when - username attribute might be C(sAMAccountName). + example for Active directory, it is common to use V(cn) as RDN attribute when + username attribute might be V(sAMAccountName). type: str uuidLDAPAttribute: description: - Name of LDAP attribute, which is used as unique object identifier (UUID) for objects - in LDAP. For many LDAP server vendors, it is C(entryUUID); however some are different. - For example for Active directory it should be C(objectGUID). If your LDAP server does + in LDAP. For many LDAP server vendors, it is V(entryUUID); however some are different. + For example for Active directory it should be V(objectGUID). If your LDAP server does not support the notion of UUID, you can use any other attribute that is supposed to be unique among LDAP users in tree. type: str @@ -167,7 +167,7 @@ options: userObjectClasses: description: - All values of LDAP objectClass attribute for users in LDAP divided by comma. - For example C(inetOrgPerson, organizationalPerson). Newly created Keycloak users + For example V(inetOrgPerson, organizationalPerson). Newly created Keycloak users will be written to LDAP with all those object classes and existing LDAP user records are found just if they contain all those object classes. type: str @@ -251,8 +251,8 @@ options: useTruststoreSpi: description: - Specifies whether LDAP connection will use the truststore SPI with the truststore - configured in standalone.xml/domain.xml. C(Always) means that it will always use it. - C(Never) means that it will not use it. C(Only for ldaps) means that it will use if + configured in standalone.xml/domain.xml. V(always) means that it will always use it. + V(never) means that it will not use it. V(ldapsOnly) means that it will use if your connection URL use ldaps. Note even if standalone.xml/domain.xml is not configured, the default Java cacerts or certificate specified by C(javax.net.ssl.trustStore) property will be used. @@ -297,7 +297,7 @@ options: connectionPoolingDebug: description: - A string that indicates the level of debug output to produce. Example valid values are - C(fine) (trace connection creation and removal) and C(all) (all debugging information). + V(fine) (trace connection creation and removal) and V(all) (all debugging information). type: str connectionPoolingInitSize: @@ -321,7 +321,7 @@ options: connectionPoolingProtocol: description: - A list of space-separated protocol types of connections that may be pooled. - Valid types are C(plain) and C(ssl). + Valid types are V(plain) and V(ssl). type: str connectionPoolingTimeout: @@ -345,14 +345,14 @@ options: serverPrincipal: description: - Full name of server principal for HTTP service including server and domain name. For - example C(HTTP/host.foo.org@FOO.ORG). Use C(*) to accept any service principal in the + example V(HTTP/host.foo.org@FOO.ORG). Use V(*) to accept any service principal in the KeyTab file. type: str keyTab: description: - Location of Kerberos KeyTab file containing the credentials of server principal. For - example C(/etc/krb5.keytab). + example V(/etc/krb5.keytab). type: str debug: @@ -451,7 +451,7 @@ options: providerId: description: - - The mapper type for this mapper (for instance C(user-attribute-ldap-mapper)). + - The mapper type for this mapper (for instance V(user-attribute-ldap-mapper)). type: str providerType: @@ -464,6 +464,7 @@ options: description: - Dict specifying the configuration options for the mapper; the contents differ depending on the value of I(identityProviderMapper). + # TODO: what is identityProviderMapper above??? type: dict extends_documentation_fragment: diff --git a/plugins/modules/keycloak_user_rolemapping.py b/plugins/modules/keycloak_user_rolemapping.py index d754e313a5..59727a346e 100644 --- a/plugins/modules/keycloak_user_rolemapping.py +++ b/plugins/modules/keycloak_user_rolemapping.py @@ -42,8 +42,8 @@ options: state: description: - State of the user_rolemapping. - - On C(present), the user_rolemapping will be created if it does not yet exist, or updated with the parameters you provide. - - On C(absent), the user_rolemapping will be removed if it exists. + - On V(present), the user_rolemapping will be created if it does not yet exist, or updated with the parameters you provide. + - On V(absent), the user_rolemapping will be removed if it exists. default: 'present' type: str choices: @@ -79,8 +79,8 @@ options: client_id: type: str description: - - Name of the client to be mapped (different than I(cid)). - - This parameter is required if I(cid) is not provided (can be replaced by I(cid) + - Name of the client to be mapped (different than O(cid)). + - This parameter is required if O(cid) is not provided (can be replaced by O(cid) to reduce the number of API calls that must be made). cid: diff --git a/plugins/modules/layman.py b/plugins/modules/layman.py index 940ac30d1b..4371e2bc02 100644 --- a/plugins/modules/layman.py +++ b/plugins/modules/layman.py @@ -32,27 +32,27 @@ options: name: description: - The overlay id to install, synchronize, or uninstall. - Use 'ALL' to sync all of the installed overlays (can be used only when I(state=updated)). + Use 'ALL' to sync all of the installed overlays (can be used only when O(state=updated)). required: true type: str list_url: description: - An URL of the alternative overlays list that defines the overlay to install. - This list will be fetched and saved under C(${overlay_defs})/${name}.xml), where + This list will be fetched and saved under C(${overlay_defs}/${name}.xml), where C(overlay_defs) is readed from the Layman's configuration. aliases: [url] type: str state: description: - - Whether to install (C(present)), sync (C(updated)), or uninstall (C(absent)) the overlay. + - Whether to install (V(present)), sync (V(updated)), or uninstall (V(absent)) the overlay. default: present choices: [present, absent, updated] type: str validate_certs: description: - - If C(false), SSL certificates will not be validated. This should only be - set to C(false) when no other option exists. Prior to 1.9.3 the code - defaulted to C(false). + - If V(false), SSL certificates will not be validated. This should only be + set to V(false) when no other option exists. Prior to 1.9.3 the code + defaulted to V(false). type: bool default: true ''' diff --git a/plugins/modules/ldap_attrs.py b/plugins/modules/ldap_attrs.py index d93b4672a4..8eadf183a5 100644 --- a/plugins/modules/ldap_attrs.py +++ b/plugins/modules/ldap_attrs.py @@ -25,10 +25,10 @@ notes: bind over a UNIX domain socket. This works well with the default Ubuntu install for example, which includes a cn=peercred,cn=external,cn=auth ACL rule allowing root to modify the server configuration. If you need to use - a simple bind to access your server, pass the credentials in I(bind_dn) - and I(bind_pw). - - For I(state=present) and I(state=absent), all value comparisons are - performed on the server for maximum accuracy. For I(state=exact), values + a simple bind to access your server, pass the credentials in O(bind_dn) + and O(bind_pw). + - For O(state=present) and O(state=absent), all value comparisons are + performed on the server for maximum accuracy. For O(state=exact), values have to be compared in Python, which obviously ignores LDAP matching rules. This should work out in most cases, but it is theoretically possible to see spurious changes when target and actual values are @@ -52,11 +52,11 @@ options: choices: [present, absent, exact] default: present description: - - The state of the attribute values. If C(present), all given attribute - values will be added if they're missing. If C(absent), all given - attribute values will be removed if present. If C(exact), the set of + - The state of the attribute values. If V(present), all given attribute + values will be added if they're missing. If V(absent), all given + attribute values will be removed if present. If V(exact), the set of attribute values will be forced to exactly those provided and no others. - If I(state=exact) and the attribute I(value) is empty, all values for + If O(state=exact) and the attribute value is empty, all values for this attribute will be removed. attributes: required: true @@ -69,16 +69,16 @@ options: readability for long string values by using YAML block modifiers as seen in the examples for this module. - Note that when using values that YAML/ansible-core interprets as other types, - like C(yes), C(no) (booleans), or C(2.10) (float), make sure to quote them if + like V(yes), V(no) (booleans), or V(2.10) (float), make sure to quote them if these are meant to be strings. Otherwise the wrong values may be sent to LDAP. ordered: required: false type: bool default: false description: - - If C(true), prepend list values with X-ORDERED index numbers in all + - If V(true), prepend list values with X-ORDERED index numbers in all attributes specified in the current task. This is useful mostly with - I(olcAccess) attribute to easily manage LDAP Access Control Lists. + C(olcAccess) attribute to easily manage LDAP Access Control Lists. extends_documentation_fragment: - community.general.ldap.documentation - community.general.attributes diff --git a/plugins/modules/ldap_entry.py b/plugins/modules/ldap_entry.py index 11fa5278dc..350feec887 100644 --- a/plugins/modules/ldap_entry.py +++ b/plugins/modules/ldap_entry.py @@ -24,8 +24,8 @@ notes: bind over a UNIX domain socket. This works well with the default Ubuntu install for example, which includes a cn=peercred,cn=external,cn=auth ACL rule allowing root to modify the server configuration. If you need to use - a simple bind to access your server, pass the credentials in I(bind_dn) - and I(bind_pw). + a simple bind to access your server, pass the credentials in O(bind_dn) + and O(bind_pw). author: - Jiri Tyr (@jtyr) requirements: @@ -38,7 +38,7 @@ attributes: options: attributes: description: - - If I(state=present), attributes necessary to create an entry. Existing + - If O(state=present), attributes necessary to create an entry. Existing entries are never modified. To assert specific attribute values on an existing entry, use M(community.general.ldap_attrs) module instead. - Each attribute value can be a string for single-valued attributes or @@ -47,13 +47,13 @@ options: readability for long string values by using YAML block modifiers as seen in the examples for this module. - Note that when using values that YAML/ansible-core interprets as other types, - like C(yes), C(no) (booleans), or C(2.10) (float), make sure to quote them if + like V(yes), V(no) (booleans), or V(2.10) (float), make sure to quote them if these are meant to be strings. Otherwise the wrong values may be sent to LDAP. type: dict default: {} objectClass: description: - - If I(state=present), value or list of values to use when creating + - If O(state=present), value or list of values to use when creating the entry. It can either be a string or an actual list of strings. type: list @@ -66,7 +66,7 @@ options: type: str recursive: description: - - If I(state=delete), a flag indicating whether a single entry or the + - If O(state=delete), a flag indicating whether a single entry or the whole branch must be deleted. type: bool default: false diff --git a/plugins/modules/ldap_passwd.py b/plugins/modules/ldap_passwd.py index 3f9e6ec4ad..5044586b0f 100644 --- a/plugins/modules/ldap_passwd.py +++ b/plugins/modules/ldap_passwd.py @@ -20,10 +20,10 @@ description: notes: - The default authentication settings will attempt to use a SASL EXTERNAL bind over a UNIX domain socket. This works well with the default Ubuntu - install for example, which includes a cn=peercred,cn=external,cn=auth ACL + install for example, which includes a C(cn=peercred,cn=external,cn=auth) ACL rule allowing root to modify the server configuration. If you need to use - a simple bind to access your server, pass the credentials in I(bind_dn) - and I(bind_pw). + a simple bind to access your server, pass the credentials in O(bind_dn) + and O(bind_pw). author: - Keller Fuchs (@KellerFuchs) requirements: @@ -36,7 +36,7 @@ attributes: options: passwd: description: - - The (plaintext) password to be set for I(dn). + - The (plaintext) password to be set for O(dn). type: str extends_documentation_fragment: - community.general.ldap.documentation diff --git a/plugins/modules/ldap_search.py b/plugins/modules/ldap_search.py index d8fa2efd07..d5e3265f0d 100644 --- a/plugins/modules/ldap_search.py +++ b/plugins/modules/ldap_search.py @@ -21,8 +21,8 @@ notes: bind over a UNIX domain socket. This works well with the default Ubuntu install for example, which includes a C(cn=peercred,cn=external,cn=auth) ACL rule allowing root to modify the server configuration. If you need to use - a simple bind to access your server, pass the credentials in I(bind_dn) - and I(bind_pw). + a simple bind to access your server, pass the credentials in O(bind_dn) + and O(bind_pw). author: - Sebastian Pfahl (@eryx12o45) requirements: @@ -59,8 +59,8 @@ options: default: false type: bool description: - - Set to C(true) to return the full attribute schema of entries, not - their attribute values. Overrides I(attrs) when provided. + - Set to V(true) to return the full attribute schema of entries, not + their attribute values. Overrides O(attrs) when provided. page_size: default: 0 type: int @@ -73,7 +73,7 @@ options: description: - If provided, all attribute values returned that are listed in this option will be Base64 encoded. - - If the special value C(*) appears in this list, all attributes will be + - If the special value V(*) appears in this list, all attributes will be Base64 encoded. - All other attribute values will be converted to UTF-8 strings. If they contain binary data, please note that invalid UTF-8 bytes will be omitted. @@ -110,7 +110,7 @@ results: value is a list. - Note that all values (for single-element lists) and list elements (for multi-valued lists) will be UTF-8 strings. Some might contain Base64-encoded binary data; which - ones is determined by the I(base64_attributes) option. + ones is determined by the O(base64_attributes) option. type: list elements: dict """ diff --git a/plugins/modules/listen_ports_facts.py b/plugins/modules/listen_ports_facts.py index bc630e1d2e..c68e883142 100644 --- a/plugins/modules/listen_ports_facts.py +++ b/plugins/modules/listen_ports_facts.py @@ -40,7 +40,8 @@ options: include_non_listening: description: - Show both listening and non-listening sockets (for TCP this means established connections). - - Adds the return values C(state) and C(foreign_address) to the returned facts. + - Adds the return values RV(ansible_facts.tcp_listen[].state), RV(ansible_facts.udp_listen[].state), + RV(ansible_facts.tcp_listen[].foreign_address), and RV(ansible_facts.udp_listen[].foreign_address) to the returned facts. type: bool default: false version_added: 5.4.0 @@ -96,13 +97,13 @@ ansible_facts: sample: "0.0.0.0" foreign_address: description: The address of the remote end of the socket. - returned: if I(include_non_listening=true) + returned: if O(include_non_listening=true) type: str sample: "10.80.0.1" version_added: 5.4.0 state: description: The state of the socket. - returned: if I(include_non_listening=true) + returned: if O(include_non_listening=true) type: str sample: "ESTABLISHED" version_added: 5.4.0 @@ -148,13 +149,13 @@ ansible_facts: sample: "0.0.0.0" foreign_address: description: The address of the remote end of the socket. - returned: if I(include_non_listening=true) + returned: if O(include_non_listening=true) type: str sample: "10.80.0.1" version_added: 5.4.0 state: description: The state of the socket. UDP is a connectionless protocol. Shows UCONN or ESTAB. - returned: if I(include_non_listening=true) + returned: if O(include_non_listening=true) type: str sample: "UCONN" version_added: 5.4.0 diff --git a/plugins/modules/lvg.py b/plugins/modules/lvg.py index 60eaaa42b2..860c333218 100644 --- a/plugins/modules/lvg.py +++ b/plugins/modules/lvg.py @@ -39,7 +39,7 @@ options: elements: str pesize: description: - - "The size of the physical extent. I(pesize) must be a power of 2 of at least 1 sector + - "The size of the physical extent. O(pesize) must be a power of 2 of at least 1 sector (where the sector size is the largest sector size of the PVs currently used in the VG), or at least 128KiB." - Since Ansible 2.6, pesize can be optionally suffixed by a UNIT (k/K/m/M/g/G), default unit is megabyte. @@ -52,7 +52,7 @@ options: default: '' pvresize: description: - - If C(true), resize the physical volume to the maximum available size. + - If V(true), resize the physical volume to the maximum available size. type: bool default: false version_added: '0.2.0' @@ -69,7 +69,7 @@ options: default: present force: description: - - If C(true), allows to remove volume group with logical volumes. + - If V(true), allows to remove volume group with logical volumes. type: bool default: false seealso: diff --git a/plugins/modules/lxc_container.py b/plugins/modules/lxc_container.py index aec8f12dc4..ddc7d3b56e 100644 --- a/plugins/modules/lxc_container.py +++ b/plugins/modules/lxc_container.py @@ -111,7 +111,7 @@ options: - debug - DEBUG description: - - Set the log level for a container where I(container_log) was set. + - Set the log level for a container where O(container_log) was set. type: str required: false default: INFO @@ -158,7 +158,7 @@ options: - clone description: - Define the state of a container. - - If you clone a container using I(clone_name) the newly cloned + - If you clone a container using O(clone_name) the newly cloned container created in a stopped state. - The running container will be stopped while the clone operation is happening and upon completion of the clone the original container @@ -178,17 +178,17 @@ notes: - Containers must have a unique name. If you attempt to create a container with a name that already exists in the users namespace the module will simply return as "unchanged". - - The I(container_command) can be used with any state except C(absent). If - used with state C(stopped) the container will be C(started), the command - executed, and then the container C(stopped) again. Likewise if I(state=stopped) + - The O(container_command) can be used with any state except V(absent). If + used with state V(stopped) the container will be V(started), the command + executed, and then the container V(stopped) again. Likewise if O(state=stopped) and the container does not exist it will be first created, - C(started), the command executed, and then C(stopped). If you use a "|" + V(started), the command executed, and then V(stopped). If you use a "|" in the variable you can use common script formatting within the variable - itself. The I(container_command) option will always execute as BASH. - When using I(container_command), a log file is created in the C(/tmp/) directory + itself. The O(container_command) option will always execute as BASH. + When using O(container_command), a log file is created in the C(/tmp/) directory which contains both C(stdout) and C(stderr) of any command executed. - - If I(archive=true) the system will attempt to create a compressed - tarball of the running container. The I(archive) option supports LVM backed + - If O(archive=true) the system will attempt to create a compressed + tarball of the running container. The O(archive) option supports LVM backed containers and will create a snapshot of the running container when creating the archive. - If your distro does not have a package for C(python3-lxc), which is a diff --git a/plugins/modules/lxd_container.py b/plugins/modules/lxd_container.py index f10fc4872f..5cf49ddd95 100644 --- a/plugins/modules/lxd_container.py +++ b/plugins/modules/lxd_container.py @@ -40,26 +40,26 @@ options: version_added: 4.8.0 architecture: description: - - 'The architecture for the instance (for example C(x86_64) or C(i686)). + - 'The architecture for the instance (for example V(x86_64) or V(i686)). See U(https://github.com/lxc/lxd/blob/master/doc/rest-api.md#post-1).' type: str required: false config: description: - - 'The config for the instance (for example C({"limits.cpu": "2"})). + - 'The config for the instance (for example V({"limits.cpu": "2"})). See U(https://github.com/lxc/lxd/blob/master/doc/rest-api.md#post-1).' - If the instance already exists and its "config" values in metadata obtained from the LXD API U(https://github.com/lxc/lxd/blob/master/doc/rest-api.md#instances-containers-and-virtual-machines) are different, this module tries to apply the configurations. - - The keys starting with C(volatile.) are ignored for this comparison when I(ignore_volatile_options=true). + - The keys starting with C(volatile.) are ignored for this comparison when O(ignore_volatile_options=true). type: dict required: false ignore_volatile_options: description: - - If set to C(true), options starting with C(volatile.) are ignored. As a result, + - If set to V(true), options starting with C(volatile.) are ignored. As a result, they are reapplied for each execution. - - This default behavior can be changed by setting this option to C(false). - - The default value changed from C(true) to C(false) in community.general 6.0.0. + - This default behavior can be changed by setting this option to V(false). + - The default value changed from V(true) to V(false) in community.general 6.0.0. type: bool required: false default: false @@ -72,26 +72,23 @@ options: devices: description: - 'The devices for the instance - (for example C({ "rootfs": { "path": "/dev/kvm", "type": "unix-char" }})). + (for example V({ "rootfs": { "path": "/dev/kvm", "type": "unix-char" }})). See U(https://github.com/lxc/lxd/blob/master/doc/rest-api.md#post-1).' type: dict required: false ephemeral: description: - - Whether or not the instance is ephemeral (for example C(true) or C(false)). + - Whether or not the instance is ephemeral (for example V(true) or V(false)). See U(https://github.com/lxc/lxd/blob/master/doc/rest-api.md#post-1). required: false type: bool source: description: - 'The source for the instance - (e.g. { "type": "image", - "mode": "pull", - "server": "https://images.linuxcontainers.org", - "protocol": "lxd", - "alias": "ubuntu/xenial/amd64" }).' + (for example V({ "type": "image", "mode": "pull", "server": "https://images.linuxcontainers.org", + "protocol": "lxd", "alias": "ubuntu/xenial/amd64" })).' - 'See U(https://github.com/lxc/lxd/blob/master/doc/rest-api.md#post-1) for complete API documentation.' - - 'Note that C(protocol) accepts two choices: C(lxd) or C(simplestreams).' + - 'Note that C(protocol) accepts two choices: V(lxd) or V(simplestreams).' required: false type: dict state: @@ -125,7 +122,7 @@ options: type: int type: description: - - Instance type can be either C(virtual-machine) or C(container). + - Instance type can be either V(virtual-machine) or V(container). required: false default: container choices: @@ -135,7 +132,7 @@ options: version_added: 4.1.0 wait_for_ipv4_addresses: description: - - If this is true, the C(lxd_container) waits until IPv4 addresses + - If this is V(true), the C(lxd_container) waits until IPv4 addresses are set to the all network interfaces in the instance after starting or restarting. required: false @@ -143,14 +140,14 @@ options: type: bool wait_for_container: description: - - If set to C(true), the tasks will wait till the task reports a + - If set to V(true), the tasks will wait till the task reports a success status when performing container operations. default: false type: bool version_added: 4.4.0 force_stop: description: - - If this is true, the C(lxd_container) forces to stop the instance + - If this is V(true), the C(lxd_container) forces to stop the instance when it stops or restarts the instance. required: false default: false @@ -201,7 +198,8 @@ notes: 2.1, the later requires python to be installed in the instance which can be done with the command module. - You can copy a file from the host to the instance - with the Ansible M(ansible.builtin.copy) and M(ansible.builtin.template) module and the C(community.general.lxd) connection plugin. + with the Ansible M(ansible.builtin.copy) and M(ansible.builtin.template) module + and the P(community.general.lxd#connection) connection plugin. See the example below. - You can copy a file in the created instance to the localhost with C(command=lxc file pull instance_name/dir/filename filename). diff --git a/plugins/modules/lxd_project.py b/plugins/modules/lxd_project.py index 983531fa08..11318ecc6d 100644 --- a/plugins/modules/lxd_project.py +++ b/plugins/modules/lxd_project.py @@ -34,7 +34,7 @@ options: type: str config: description: - - 'The config for the project (for example C({"features.profiles": "true"})). + - 'The config for the project (for example V({"features.profiles": "true"})). See U(https://linuxcontainers.org/lxd/docs/master/projects/).' - If the project already exists and its "config" value in metadata obtained from @@ -98,7 +98,7 @@ options: running this module using the following command: C(lxc config set core.trust_password ) See U(https://www.stgraber.org/2016/04/18/lxd-api-direct-interaction/).' - - If I(trust_password) is set, this module send a request for + - If O(trust_password) is set, this module send a request for authentication before sending any requests. required: false type: str @@ -146,7 +146,7 @@ logs: elements: dict contains: type: - description: Type of actions performed, currently only C(sent request). + description: Type of actions performed, currently only V(sent request). type: str sample: "sent request" request: @@ -166,7 +166,7 @@ logs: type: str sample: "(too long to be placed here)" timeout: - description: Timeout of HTTP request, C(null) if unset. + description: Timeout of HTTP request, V(null) if unset. type: int sample: null response: