Chapter 16. Using declarative configuration 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 Red Hat Advanced Cluster Security for Kubernetes (RHACS) 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 RHACS 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 RHACS. 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. 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. 16.1. Restrictions for resources created from declarative configuration 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 RHACS 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 RHACS portal or the API. 16.2. Creating declarative configurations Use roxctl to create the YAML files that store the configurations, create a config map from the files, and apply the config map. 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. 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. USD roxctl declarative-config create permission-set \ --name="restricted" \ --description="Restriction permission set that only allows \ access to Administration and Access resources" \ --resource-with-access=Administration=READ_WRITE_ACCESS \ --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. USD roxctl declarative-config create role \ --name="restricted" \ --description="Restricted role that only allows access to Administration and Access" \ --permission-set="restricted" \ --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. USD kubectl create configmap declarative-configurations \ 1 --from-file permission-set.yaml --from-file role.yaml \ -o yaml --namespace=stackrox > declarative-configs.yaml 1 For OpenShift Container Platform, use oc create . Apply the config map by entering the following command: USD kubectl apply -f declarative-configs.yaml 1 1 For OpenShift Container Platform, use oc apply . After you apply the config map, configuration information extracted from Central 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 RHACS web portal. The Origin field indicates Declarative if the resource was created by using declarative configuration. Note You cannot edit resources created from declarative configurations in the RHACS 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. 16.3. Declarative configuration examples 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. 16.3.1. Declarative configuration authentication provider example Declarative configuration authentication provider example name: A sample auth provider minimumRole: Analyst 1 uiEndpoint: central.custom-domain.com:443 2 extraUIEndpoints: 3 - central-alt.custom-domain.com:443 groups: 4 - key: email 5 value: example@example.com role: Admin 6 - key: groups value: reviewers role: Analyst requiredAttributes: 7 - key: org_id value: "12345" claimMappings: 8 - path: org_id value: my_org_id oidc: 9 issuer: sample.issuer.com 10 mode: auto 11 clientID: CLIENT_ID clientSecret: CLIENT_SECRET clientSecret: CLIENT_SECRET iap: 12 audience: audience saml: 13 spIssuer: sample.issuer.com metadataURL: sample.provider.com/metadata saml: 14 spIssuer: sample.issuer.com cert: | 15 ssoURL: saml.provider.com idpIssuer: idp.issuer.com userpki: certificateAuthorities: | 16 certificate 17 openshift: 18 enable: true 1 Identifies the minimum role that will be assigned by default to any user logging in. If left blank, the value is None . 2 Use the user interface endpoint of your Central instance. 3 If your Central instance is exposed to different endpoints, specify them here. 4 These fields map users to specific roles, based on their attributes. 5 The key can be any claim returned from the authentication provider. 6 Identifies the role that the users are given. You can use a default role or a declaratively-created role. 7 Optional: Use these fields if attributes returned from the authentication provider are required; for example, if the audience is limited to a specific organization or group. 8 Optional: Use these fields if claims returned from the identity provider should be mapped to custom claims. 9 This section is required only for OpenID Connect (OIDC) authentication providers. 10 Identifies the expected issuer for the token. 11 Identifies the OIDC callback mode. Possible values are auto , post , query , and fragment . The preferred value is auto . 12 This section is required only for Google Identity-Aware Proxy (IAP) authentication providers. 13 This section is required only for Security Assertion Markup Language (SAML) 2.0 dynamic configuration authentication providers. 14 This section is required only for SAML 2.0 static configuration authentication providers. 15 Include the certificate in Privacy Enhanced Mail (PEM) format. 16 This section is required only for authentication with user certificates. 17 Include the certificate in PEM format. 18 This section is required only for OpenShift Auth authentication providers. 16.3.2. Declarative configuration permission set example Declarative configuration permission set example name: A sample permission set description: A sample permission set created declaratively resources: - resource: Integration 1 access: READ_ACCESS 2 - resource: Administration access: READ_WRITE_ACCESS 1 For a full list of supported resources, go to Access Control Permission Sets . 2 Access can be either READ_ACCESS or READ_WRITE_ACCESS . 16.3.3. Declarative configuration access scope example Declarative configuration access scope example name: A sample access scope description: A sample access scope created declaratively rules: included: - cluster: secured-cluster-A 1 namespaces: - namespaceA - cluster: secured-cluster-B 2 clusterLabelSelectors: - requirements: - requirements: - key: kubernetes.io/metadata.name operator: IN 3 values: - production - staging - environment 1 Identifies a cluster where only specific namespaces are included within the access scope. 2 Identifies a cluster where all namespaces are included within the access scope. 3 Identifies the Operator to use for the label selection. Valid values are IN , NOT_IN , EXISTS , and NOT_EXISTS . 16.3.4. Declarative configuration role example Declarative configuration role example name: A sample role description: A sample role created declaratively permissionSet: A sample permission set 1 accessScope: Unrestricted 2 1 Name of the permission set; can be either one of the system permission sets or a declaratively-created permission set. 2 Name of the access scope; can be either one of the system access scopes or a declaratively-created access scope. 16.4. Troubleshooting declarative configuration 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 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. 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. 16.5. Additional resources Install Central using Helm charts with customizations (Red Hat OpenShift) Install Central using Helm charts with customizations (other Kubernetes platforms)

Commands:
roxctl declarative-config create permission-set --name="restricted" --description="Restriction permission set that only allows access to Administration and Access resources" --resource-with-access=Administration=READ_WRITE_ACCESS --resource-with-access=Access=READ_ACCESS > permission-set.yaml
roxctl declarative-config create role --name="restricted" --description="Restricted role that only allows access to Administration and Access" --permission-set="restricted" --access-scope="Unrestricted" > role.yaml
kubectl create configmap declarative-configurations \ 1 --from-file permission-set.yaml --from-file role.yaml -o yaml --namespace=stackrox > declarative-configs.yaml
kubectl apply -f declarative-configs.yaml 1
name: A sample auth provider minimumRole: Analyst 1 uiEndpoint: central.custom-domain.com:443 2 extraUIEndpoints: 3 - central-alt.custom-domain.com:443 groups: 4 - key: email 5 value: example@example.com role: Admin 6 - key: groups value: reviewers role: Analyst requiredAttributes: 7 - key: org_id value: "12345" claimMappings: 8 - path: org_id value: my_org_id oidc: 9 issuer: sample.issuer.com 10 mode: auto 11 clientID: CLIENT_ID clientSecret: CLIENT_SECRET clientSecret: CLIENT_SECRET iap: 12 audience: audience saml: 13 spIssuer: sample.issuer.com metadataURL: sample.provider.com/metadata saml: 14 spIssuer: sample.issuer.com cert: | 15 ssoURL: saml.provider.com idpIssuer: idp.issuer.com userpki: certificateAuthorities: | 16 certificate 17 openshift: 18 enable: true
name: A sample permission set description: A sample permission set created declaratively resources: - resource: Integration 1 access: READ_ACCESS 2 - resource: Administration access: READ_WRITE_ACCESS
name: A sample access scope description: A sample access scope created declaratively rules: included: - cluster: secured-cluster-A 1 namespaces: - namespaceA - cluster: secured-cluster-B 2 clusterLabelSelectors: - requirements: - requirements: - key: kubernetes.io/metadata.name operator: IN 3 values: - production - staging - environment
name: A sample role description: A sample role created declaratively permissionSet: A sample permission set 1 accessScope: Unrestricted 2