Using declarative configuration

Restrictions for resources created from declarative configuration
Creating declarative configurations
Declarative configuration examples
Troubleshooting declarative configuration
Additional resources

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.

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.

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.

$ 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.

$ 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.
```
$ 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.

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.

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.

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.

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.

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, navigate to Access Control → Permission Sets.
2	Access can be either `READ_ACCESS` or `READ_WRITE_ACCESS`.

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

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`.

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.

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.