From d047ee868b8fb4485e5963c0227b384b9e2eb0a5 Mon Sep 17 00:00:00 2001 From: Agil Antony Date: Tue, 26 May 2026 17:36:26 +0530 Subject: [PATCH] ROX33164 Fixing DITA errors in configuration/declarative-configuration-using.adoc --- .../declarative-configuration-using.adoc | 32 ++-- ...clarative-config-example-access-scope.adoc | 38 +++++ ...larative-config-example-auth-provider.adoc | 75 ++++++++ ...arative-config-example-permission-set.adoc | 28 +++ modules/declarative-config-example-role.adoc | 25 +++ ...tive-config-example-short-lived-token.adoc | 32 ++++ .../declarative-configuration-examples.adoc | 161 +----------------- .../declarative-configuration-overview.adoc | 16 ++ ...arative-configuration-resource-create.adoc | 22 +-- ...eclarative-configuration-restrictions.adoc | 16 ++ ...arative-configuration-troubleshooting.adoc | 8 +- 11 files changed, 267 insertions(+), 186 deletions(-) create mode 100644 modules/declarative-config-example-access-scope.adoc create mode 100644 modules/declarative-config-example-auth-provider.adoc create mode 100644 modules/declarative-config-example-permission-set.adoc create mode 100644 modules/declarative-config-example-role.adoc create mode 100644 modules/declarative-config-example-short-lived-token.adoc create mode 100644 modules/declarative-configuration-overview.adoc create mode 100644 modules/declarative-configuration-restrictions.adoc diff --git a/configuration/declarative-configuration-using.adoc b/configuration/declarative-configuration-using.adoc index 166f88341ebe..1018ce237a54 100644 --- a/configuration/declarative-configuration-using.adoc +++ b/configuration/declarative-configuration-using.adoc @@ -7,28 +7,36 @@ include::modules/common-attributes.adoc[] toc::[] [role="_abstract"] - With declarative configuration, you can update configurations by storing them in files in repositories and apply them to the system. Declarative configuration is useful, for example, if you are using a GitOps workflow. You can currently use declarative configuration in {rh-rhacs-first} for authentication and authorization resources such as authentication providers, roles, permission sets, and access scopes. -To use declarative configuration, you create YAML files that contain configuration information about authentication and authorization resources. These files, or configurations, are added to {product-title-short} by using a mount point during Central installation. See the installation documentation in the "Additional resources" section for more information on configuring mount points when installing {product-title-short}. +//Declarative configuration overview +include::modules/declarative-configuration-overview.adoc[leveloffset=+1] -The configuration files used with declarative configuration are stored in config maps or secrets, depending on the type of resource. Store configurations for authentication providers in a secret for greater security. You can store other configurations in config maps. +//Restrictions for resources created from declarative configuration +include::modules/declarative-configuration-restrictions.adoc[leveloffset=+1] -A single config map or secret can contain more than one configuration of multiple resource types. This allows you to limit the number of volume mounts for the Central instance. +//Creating declarative configurations +include::modules/declarative-configuration-resource-create.adoc[leveloffset=+1] -[id="restrictions-declarative-config-resources"] -== Restrictions for resources created from declarative configuration +//Declarative configuration examples +include::modules/declarative-configuration-examples.adoc[leveloffset=+1] -Because resources can reference other resources (for example, a role can reference both a permission set and access scope), the following restrictions for references apply: +include::modules/declarative-config-example-auth-provider.adoc[leveloffset=+2] -* A declarative configuration can only reference a resource that is either also created declaratively or a system {product-title-short} resource; for example, a resource such as the `Admin` or `Analyst` system role or permission set. -* All references between resources use names to identify the resource; therefore, all names within the same resource type must be unique. -* Resources created from declarative configuration can only be modified or deleted by altering the declarative configuration files. You cannot change these resources by using the {product-title-short} portal or the API. +include::modules/declarative-config-example-short-lived-token.adoc[leveloffset=+2] -include::modules/declarative-configuration-resource-create.adoc[leveloffset=+1] +[role="_additional-resources"] +.Additional resources +* xref:../operating/manage-user-access/configure-short-lived-access.adoc#configure-short-lived-access_configure-short-lived-access[Configuring short-lived access] +* xref:../integration/integrate-using-short-lived-tokens.adoc#integrate-using-short-lived-tokens[Integrating {product-title-short} using short-lived tokens] -include::modules/declarative-configuration-examples.adoc[leveloffset=+1] +include::modules/declarative-config-example-permission-set.adoc[leveloffset=+2] + +include::modules/declarative-config-example-access-scope.adoc[leveloffset=+2] + +include::modules/declarative-config-example-role.adoc[leveloffset=+2] +//Troubleshooting declarative configuration include::modules/declarative-configuration-troubleshooting.adoc[leveloffset=+1] [role="_additional-resources"] diff --git a/modules/declarative-config-example-access-scope.adoc b/modules/declarative-config-example-access-scope.adoc new file mode 100644 index 000000000000..a433179a4f10 --- /dev/null +++ b/modules/declarative-config-example-access-scope.adoc @@ -0,0 +1,38 @@ +// Module included in the following assemblies: +// +// * configuration/declarative-configuration-using.adoc + +:_mod-docs-content-type: REFERENCE +[id="declarative-config-example-access-scope_{context}"] += Declarative configuration access scope example + +[role="_abstract"] +Example YAML configuration for creating an access scope by using declarative configuration. + +[source,yaml] +---- +name: A sample access scope +description: A sample access scope created declaratively +rules: + included: + - cluster: secured-cluster-A + namespaces: + - namespaceA + - cluster: secured-cluster-B + clusterLabelSelectors: + - requirements: + - key: kubernetes.io/metadata.name + operator: IN + values: + - production + - staging + - environment +---- + +where: + +-- +`rules.included.cluster`:: Specifies a cluster where the access scope includes only specific namespaces. +`rules.included.cluster`:: Specifies a cluster where the access scope includes all namespaces. +`rules.clusterLabelSelectors.requirements.operator`:: Specifies the Operator to use for the label selection. Valid values are `IN`, `NOT_IN`, `EXISTS`, and `NOT_EXISTS`. +-- diff --git a/modules/declarative-config-example-auth-provider.adoc b/modules/declarative-config-example-auth-provider.adoc new file mode 100644 index 000000000000..29fcb26d3c92 --- /dev/null +++ b/modules/declarative-config-example-auth-provider.adoc @@ -0,0 +1,75 @@ +// Module included in the following assemblies: +// +// * configuration/declarative-configuration-using.adoc + +:_mod-docs-content-type: REFERENCE +[id="declarative-config-example-auth-provider_{context}"] += Declarative configuration authentication provider example + +[role="_abstract"] +Example YAML configuration for creating an authentication provider by using declarative configuration. + +[source,yaml] +---- +name: A sample auth provider +minimumRole: Analyst +uiEndpoint: central.custom-domain.com:443 +extraUIEndpoints: + - central-alt.custom-domain.com:443 +groups: + - key: email + value: example@example.com + role: Admin + - key: groups + value: reviewers + role: Analyst +requiredAttributes: + - key: org_id + value: "12345" +claimMappings: + - path: org_id + value: my_org_id +oidc: + issuer: sample.issuer.com + mode: auto + clientID: CLIENT_ID + clientSecret: CLIENT_SECRET +clientSecret: CLIENT_SECRET +iap: + audience: audience +saml: + spIssuer: sample.issuer.com + metadataURL: sample.provider.com/metadata +saml: + spIssuer: sample.issuer.com + cert: | + ssoURL: saml.provider.com + idpIssuer: idp.issuer.com +userpki: + certificateAuthorities: | + certificate +openshift: + enable: true +---- + +where: + +-- +`minimumRole`:: Specifies the minimum role that the system assigns by default to any user logging in. If left blank, the value is `None`. +`uiEndpoint`:: Specifies the user interface endpoint of your Central instance. +`extraUIEndpoints`:: Specifies whether your Central instance exposes different endpoints. +`groups`:: Specifies the specific roles to map users based on their attributes. +`groups.key`:: Specifies the key that can be any claim the authentication provider returns. +`groups.role`:: Specifies the role that the system gives to the users. You can use a default role or a declaratively-created role. +`requiredAttributes`:: Specifies whether the authentication provider requires the returned attributes, for example, if the audience limits to a specific organization or group. This is optional. +`claimMappings`:: Specifies whether to map the claims the identity provider returns to custom claims. This is optional. +`oidc`:: Specifies whether to configure the system to use OpenID Connect (OIDC) as an authentication method. +`oidc.issuer`:: Specifies the expected issuer for the token. +`oidc.mode`:: Specifies the OIDC callback mode. Possible values are `auto`, `post`, `query`, and `fragment`. The preferred value is `auto`. +`iap`:: Specifies whether to configure the system to use Google Identity-Aware Proxy (IAP) as an authentication method. +`saml`:: Specifies whether to configure the system to use Security Assertion Markup Language (SAML) 2.0 dynamic or static configuration as an authentication method. +`saml.cert`:: Specifies the certificate in Privacy Enhanced Mail (PEM) format. +`userpki.certificateAuthorities`:: Specifies whether to configure the system for authentication with user certificates. +`userpki.certificate`:: Specifies the certificate in PEM format. +`openshift`:: Specifies whether to configure the system for OpenShift Auth authentication providers. +-- diff --git a/modules/declarative-config-example-permission-set.adoc b/modules/declarative-config-example-permission-set.adoc new file mode 100644 index 000000000000..f4a798a0ff29 --- /dev/null +++ b/modules/declarative-config-example-permission-set.adoc @@ -0,0 +1,28 @@ +// Module included in the following assemblies: +// +// * configuration/declarative-configuration-using.adoc + +:_mod-docs-content-type: REFERENCE +[id="declarative-config-example-permission-set_{context}"] += Declarative configuration permission set example + +[role="_abstract"] +Example YAML configuration for creating a permission set by using declarative configuration. + +[source,yaml] +---- +name: A sample permission set +description: A sample permission set created declaratively +resources: +- resource: Integration + access: READ_ACCESS +- resource: Administration + access: READ_WRITE_ACCESS +---- + +where: + +-- +`resources.resource`:: Specifies a full list of supported resources. For more information, go to *Access Control* -> *Permission Sets*. +`resources.access`:: Specifies that the access can be either `READ_ACCESS` or `READ_WRITE_ACCESS`. +-- diff --git a/modules/declarative-config-example-role.adoc b/modules/declarative-config-example-role.adoc new file mode 100644 index 000000000000..4c1a3638346e --- /dev/null +++ b/modules/declarative-config-example-role.adoc @@ -0,0 +1,25 @@ +// Module included in the following assemblies: +// +// * configuration/declarative-configuration-using.adoc + +:_mod-docs-content-type: REFERENCE +[id="declarative-config-example-role_{context}"] += Declarative configuration role example + +[role="_abstract"] +Example YAML configuration for creating a role by using declarative configuration. + +[source,yaml] +---- +name: A sample role +description: A sample role created declaratively +permissionSet: A sample permission set +accessScope: Unrestricted +---- + +where: + +-- +`permissionSet`:: Specifies the name of the permission set; can be either one of the system permission sets or a declaratively-created permission set. +`accessScope`:: Specifies the name of the access scope; can be either one of the system access scopes or a declaratively-created access scope. +-- diff --git a/modules/declarative-config-example-short-lived-token.adoc b/modules/declarative-config-example-short-lived-token.adoc new file mode 100644 index 000000000000..11ee7320a772 --- /dev/null +++ b/modules/declarative-config-example-short-lived-token.adoc @@ -0,0 +1,32 @@ +// Module included in the following assemblies: +// +// * configuration/declarative-configuration-using.adoc + +:_mod-docs-content-type: REFERENCE +[id="declarative-config-example-short-lived-token_{context}"] += Declarative configuration short-lived token example + +[role="_abstract"] +Example YAML configuration for creating a short-lived token configuration by using declarative configuration. + +[source,yaml] +---- +issuer: https://token.actions.githubusercontent.com +type: GITHUB_ACTION +tokenExpirationDuration: 20m +mappings: + - key: sub + value: repos:stackrox:stackrox + role: Analyst +---- + +where: + +-- +`issuer`:: Specifies the expected issuer for the token to exchange against a short-lived one. +`type`:: Specifies the configuration type. See "Configuring short-lived access" and "Integrating {product-title-short} using short-lived access tokens" for more information. +`tokenExpirationDuration`:: Specifies the token lifetime in the *XhYmZs* format. The lifetime cannot be longer than 24 hours. +`mappings`:: Specifies the roles to which the system maps users, based on their attributes. +`mappings.key`:: Specifies that the key can be any claim the issuer returns. +`mappings.role`:: Specifies the role that the system gives to the users. You can use a default role or a declaratively-created one. +-- diff --git a/modules/declarative-configuration-examples.adoc b/modules/declarative-configuration-examples.adoc index ce98ee5015d5..5ff181898d2d 100644 --- a/modules/declarative-configuration-examples.adoc +++ b/modules/declarative-configuration-examples.adoc @@ -7,163 +7,4 @@ = Declarative configuration examples [role="_abstract"] -You can create declarative configurations by using the following examples as a guide. Use the `roxctl declarative-config lint` command to verify that your configurations are valid. - -[id="declarative-config-example-auth-provider"] -== Declarative configuration authentication provider example - -[source,yaml] ----- -name: A sample auth provider -minimumRole: Analyst -uiEndpoint: central.custom-domain.com:443 -extraUIEndpoints: - - central-alt.custom-domain.com:443 -groups: - - key: email - value: example@example.com - role: Admin - - key: groups - value: reviewers - role: Analyst -requiredAttributes: - - key: org_id - value: "12345" -claimMappings: - - path: org_id - value: my_org_id -oidc: - issuer: sample.issuer.com - mode: auto - clientID: CLIENT_ID - clientSecret: CLIENT_SECRET -clientSecret: CLIENT_SECRET -iap: - audience: audience -saml: - spIssuer: sample.issuer.com - metadataURL: sample.provider.com/metadata -saml: - spIssuer: sample.issuer.com - cert: | - ssoURL: saml.provider.com - idpIssuer: idp.issuer.com -userpki: - certificateAuthorities: | - certificate -openshift: - enable: true ----- - -where: - --- -`minimumRole`:: Specifies the minimum role that will be assigned by default to any user logging in. If left blank, the value is `None`. -`uiEndpoint`:: Specifies the user interface endpoint of your Central instance. -`extraUIEndpoints`:: Specifies whether your Central instance is exposed to different endpoints. -`groups`:: Specifies the specific roles to map users based on their attributes. -`groups.key`:: Specifies the key that can be any claim returned from the authentication provider. -`groups.role`:: Specifies the role that the users are given. You can use a default role or a declaratively-created role. -`requiredAttributes`:: Specifies whether the attributes returned from the authentication provider are required, for example, if the audience is limited to a specific organization or group. This is optional. -`claimMappings`:: Specifies whether the claims returned from the identity provider should be mapped to custom claims. This is optional. -`oidc`:: Specifies whether the system is configured to use OpenID Connect (OIDC) as an authentication method. -`oidc.issuer`:: Specifies the expected issuer for the token. -`oidc.mode`:: Specifies the OIDC callback mode. Possible values are `auto`, `post`, `query`, and `fragment`. The preferred value is `auto`. -`iap`:: Specifies whether the system is configured to use Google Identity-Aware Proxy (IAP) as an authentication method. -`saml`:: Specifies whether the system is configured to use Security Assertion Markup Language (SAML) 2.0 dynamic or static configuration as an authentication method. -`saml.cert`:: Specifies the certificate in Privacy Enhanced Mail (PEM) format. -`userpki.certificateAuthorities`:: Specifies whether the system is configured for authentication with user certificates. -`userpki.certificate`:: Specifies the certificate in PEM format. -`openshift`:: Specifies whether the system is configured for OpenShift Auth authentication providers. --- -[id="declarative-config-example-short-lived-token"] -== Declarative configuration short-lived token example - -[source,yaml] ----- -issuer: https://token.actions.githubusercontent.com -type: GITHUB_ACTION -tokenExpirationDuration: 20m -mappings: - - key: sub - value: repos:stackrox:stackrox - role: Analyst ----- - -where: - --- -`issuer`:: Specifies the expected issuer for the token to exchange against a short-lived one. -`type`:: Specifies the configuration type. See "Configuring short-lived access" and "Integrating {product-title-short} using short-lived access tokens" for more information. -`tokenExpirationDuration`:: Specifies the token lifetime in the *XhYmZs* format. The lifetime cannot be longer than 24 hours. -`mappings`:: Specifies the roles to which users are mapped, based on their attributes. -`mappings.key`:: Specifies that the key can be any claim returned from the issuer. -`mappings.role`:: Specifies the role that the users are given. You can use a default role or a declaratively-created one. --- -[id="declarative-config-example-permission-set"] -== Declarative configuration permission set example - -[source,yaml] ----- -name: A sample permission set -description: A sample permission set created declaratively -resources: -- resource: Integration - access: READ_ACCESS -- resource: Administration - access: READ_WRITE_ACCESS ----- - -where: - --- -`resources.resource`:: Specifies a full list of supported resources. For more information, go to *Access Control* -> *Permission Sets*. -`resources.access`:: Specifies that the access can be either `READ_ACCESS` or `READ_WRITE_ACCESS`. --- -[id="declarative-config-example-access-scope"] -== Declarative configuration access scope example - -[source,yaml] ----- -name: A sample access scope -description: A sample access scope created declaratively -rules: - included: - - cluster: secured-cluster-A - namespaces: - - namespaceA - - cluster: secured-cluster-B - clusterLabelSelectors: - - requirements: - - key: kubernetes.io/metadata.name - operator: IN - values: - - production - - staging - - environment ----- - -where: - --- -`rules.included.cluster`:: Specifies a cluster where only specific namespaces are included within the access scope. -`rules.included.cluster`:: Specifies a cluster where all namespaces are included within the access scope. -`rules.clusterLabelSelectors.requirements.operator`:: Specifies the Operator to use for the label selection. Valid values are `IN`, `NOT_IN`, `EXISTS`, and `NOT_EXISTS`. --- -[id="declarative-config-example-role"] -== Declarative configuration role example - -[source,yaml] ----- -name: A sample role -description: A sample role created declaratively -permissionSet: A sample permission set -accessScope: Unrestricted ----- - -where: - --- -`permissionSet`:: Specifies the name of the permission set; can be either one of the system permission sets or a declaratively-created permission set. -`accessScope`:: Specifies the name of the access scope; can be either one of the system access scopes or a declaratively-created access scope. --- \ No newline at end of file +You can create declarative configurations by using the following examples as a guide. Use the `roxctl declarative-config lint` command to verify that your configurations are valid. \ No newline at end of file diff --git a/modules/declarative-configuration-overview.adoc b/modules/declarative-configuration-overview.adoc new file mode 100644 index 000000000000..355f0f766ba0 --- /dev/null +++ b/modules/declarative-configuration-overview.adoc @@ -0,0 +1,16 @@ +// Module included in the following assemblies: +// +// * configuration/declarative-configuration-using.adoc + +:_mod-docs-content-type: CONCEPT +[id="declarative-configuration-overview_{context}"] += Declarative configuration overview + +[role="_abstract"] +With declarative configuration, you can update configurations by storing them in files in repositories and apply them to the system by using config maps or secrets. + +To use declarative configuration, you create YAML files that contain configuration information about authentication and authorization resources. You add these files, or configurations, to {product-title-short} by using a mount point during Central installation. See the installation documentation in the "Additional resources" section for more information about configuring mount points when installing {product-title-short}. + +You store the configuration files used with declarative configuration in config maps or secrets, depending on the type of resource. Store configurations for authentication providers in a secret for greater security. You can store other configurations in config maps. + +A single config map or secret can contain more than one configuration of many resource types. This configuration limits the number of volume mounts for the Central instance. diff --git a/modules/declarative-configuration-resource-create.adoc b/modules/declarative-configuration-resource-create.adoc index 273b3147580b..a1f6aee0e769 100644 --- a/modules/declarative-configuration-resource-create.adoc +++ b/modules/declarative-configuration-resource-create.adoc @@ -5,6 +5,7 @@ [id="declarative-configuration-resource-create_{context}"] = Creating declarative configurations +[role="_abstract"] Use `roxctl` to create the YAML files that store the configurations, create a config map from the files, and apply the config map. [NOTE] @@ -13,11 +14,11 @@ For {ocp}, use `oc` instead of `kubectl`. ==== .Prerequisites -* You have added the mount for the config map or secret during the installation of Central. In this example, the config map is called "declarative-configs". See the installation documentation listed in the "Additional resources" section for more information. +* You have added the mount for the config map or secret during the installation of Central. In this example, the config map has the name "declarative-configs". See the installation documentation for more information. .Procedure -. Create the permission set by entering the following command. This example creates a permission set named "restricted" and is saved as the `permission-set.yaml` file. It sets read and write access for the `Administration` resource and read access to the Access resource. +. Create the permission set by entering the following command. This example creates a permission set named "restricted" and saves it as the `permission-set.yaml` file. It sets read and write access for the `Administration` resource and read access to the Access resource. + [source,terminal,subs=attributes+] ---- @@ -29,7 +30,7 @@ access to Administration and Access resources" \ --resource-with-access=Access=READ_ACCESS > permission-set.yaml ---- -. Create the role that allows access to the `Administration` and `Access` resources by entering the following command. This example creates a role named "restricted" and is saved as the `role.yaml` file. +. Create the role that allows access to the `Administration` and `Access` resources by entering the following command. This example creates a role named "restricted" and saves it as the `role.yaml` file. + [source,terminal,subs=attributes+] ---- @@ -40,7 +41,7 @@ $ roxctl declarative-config create role \ --access-scope="Unrestricted" > role.yaml ---- -. Create a config map from the two YAML files that were created in the earlier steps by entering the following command. This example creates the `declarative-configurations` config map. +. Create a config map from the two YAML files that you created in the earlier steps by entering the following command. This example creates the `declarative-configurations` config map. + [source,terminal,subs=attributes+] ---- @@ -56,22 +57,23 @@ $ kubectl create configmap declarative-configurations \ $ kubectl apply -f declarative-configs.yaml ---- + -After you apply the config map, configuration information extracted from Central creates the resources. +After you apply the config map, Central extracts the configuration information and creates the resources. + [NOTE] ==== Although the watch interval is 5 seconds, as described in the following paragraph, there can be a delay in propagating changes from the config map to the Central mount. ==== ++ You can configure the following intervals to specify how declarative configurations interact with Central: - ++ * Configuration watch interval: The interval for Central to check for changes is every 5 seconds. You can configure this interval by using the `ROX_DECLARATIVE_CONFIG_WATCH_INTERVAL` environment variable. * Reconciliation interval: By default, declarative configuration reconciliation with Central occurs every 20 seconds. You can configure this interval by using the `ROX_DECLARATIVE_CONFIG_RECONCILE_INTERVAL` environment variable. - -After creating authentication and authorization resources by using declarative configuration, you can view them in the *Access Control* page in the {product-title-short} web portal. The *Origin* field indicates `Declarative` if the resource was created by using declarative configuration. - ++ +After creating authentication and authorization resources by using declarative configuration, you can view them in the *Access Control* page in the {product-title-short} web portal. The *Origin* field indicates `Declarative` if you created the resource by using declarative configuration. ++ [NOTE] ==== You cannot edit resources created from declarative configurations in the {product-title-short} web portal. You must edit the configuration files directly to make changes to these resources. ==== - ++ You can view the status of declarative configurations by navigating to *Platform Configuration* -> *System Health* and scrolling to the *Declarative configuration* section. \ No newline at end of file diff --git a/modules/declarative-configuration-restrictions.adoc b/modules/declarative-configuration-restrictions.adoc new file mode 100644 index 000000000000..6128b82a6e9d --- /dev/null +++ b/modules/declarative-configuration-restrictions.adoc @@ -0,0 +1,16 @@ +// Module included in the following assemblies: +// +// * configuration/declarative-configuration-using.adoc + +:_mod-docs-content-type: CONCEPT +[id="restrictions-declarative-config-resources_{context}"] += Restrictions for resources created from declarative configuration + +[role="_abstract"] +Resources created from declarative configuration have specific restrictions regarding references, naming, and modification. + +Because resources can reference other resources (for example, a role can reference both a permission set and access scope), the following restrictions for references apply: + +* A declarative configuration can only reference a resource that is either also created declaratively or a system {product-title-short} resource; for example, a resource such as the `Admin` or `Analyst` system role or permission set. +* All references between resources use names to identify the resource; therefore, all names within the same resource type must be unique. +* You can only change or delete resources created from declarative configuration by altering the declarative configuration files. You cannot change these resources by using the {product-title-short} portal or the API. diff --git a/modules/declarative-configuration-troubleshooting.adoc b/modules/declarative-configuration-troubleshooting.adoc index 48363e611279..29090eda3f58 100644 --- a/modules/declarative-configuration-troubleshooting.adoc +++ b/modules/declarative-configuration-troubleshooting.adoc @@ -8,12 +8,12 @@ [role="_abstract"] You can use the error messages displayed in the *Declarative configuration* section of the *Platform Configuration* -> *System Health* page to help in troubleshooting. The `roxctl declarative-config` command also includes a `lint` option to validate the configuration file and help you detect errors. -The error messages displayed in the *Declarative configuration* section of the *Platform Configuration* -> *System Health* page provide information about issues with declarative configurations. Problems with declarative configurations can be caused by the following conditions: +The error messages displayed in the *Declarative configuration* section of the *Platform Configuration* -> *System Health* page give information about issues with declarative configurations. The following conditions can cause problems with declarative configurations: * The format of the configuration file is not in valid YAML. -* The configuration file contains invalid values, such as invalid access within a permission set. -* Invalid storage constraints exist, such as resource names are not unique or the configuration contains invalid references to a resource. +* The configuration file has invalid values, such as invalid access within a permission set. +* Invalid storage constraints exist, such as resource names are not unique or the configuration has invalid references to a resource. To validate configuration files, check for errors in configuration files, and make sure that there are no invalid storage constraints when creating and updating configuration files, use the `roxctl declarative-config lint` command. -To troubleshoot a storage constraint during deletion, check if the resource has been marked as `Declarative Orphaned`. This indicates that the declarative configuration referenced by a resource was deleted (for example, if the declarative configuration for a permission set that was referenced by a role was deleted). To correct this error, edit the resource to point to a new permission set, or restore the declarative configuration that was deleted. \ No newline at end of file +To troubleshoot a storage constraint during deletion, check if the system marked the resource as `Declarative Orphaned`. This indicates that someone deleted the declarative configuration that a resource referenced (for example, if someone deleted the declarative configuration for a permission set that a role referenced). To correct this error, edit the resource to point to a new permission set, or restore the deleted declarative configuration. \ No newline at end of file