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 references" 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
AdminorAnalystsystem 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.yamlfile. It sets read and write access for theAdministrationresource and read access to the Access resource.$ 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
AdministrationandAccessresources by entering the following command. This example creates a role named "restricted" and is saved as therole.yamlfile.$ 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-configurationsconfig map.$ 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:
$ 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.
NoteAlthough 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_INTERVALenvironment 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_INTERVALenvironment 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.
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
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, andfragment. The preferred value isauto. - 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
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:
key: kubernetes.io/metadata.name
operator: IN 3
values:
- production
- staging
- environment
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
16.4. Troubleshooting declarative configuration
You can use the error messages displayed in the Declarative configuration section of the Platform Configuration 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
- 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.
