Configuring governance in the Cloud Manager

How to add governance rulesets in the Cloud Manager to validate and enforce organizational governance policies and best practices across your API development process.

• To create a new API or product ruleset by using the Cloud Manager UI, complete the following steps.
  1. In the side menu bar, click Governance.
     The Governance page is displayed.
  2. If you want to create an API ruleset, click the API tab. If you want to create a product ruleset, click the Product tab.
     The manage rulesets page is displayed.
  3. In the Global rulesets section, click Add > Create from scratch.
     The Create ruleset wizard opens.
  4. Provide the following Ruleset info details.

     Property label	Required	Description	Data type
     Title	Yes	A short descriptive name for the ruleset. This name is displayed in the list of global rulesets.	String
     Name	Yes	An auto-generated, sluggified, string that is based on the title. It is not editable.	String
     Version	Yes	The version number defaults to 1.0.0, but can be edited. You can have rulesets with the same name, but with different version numbers. The version number must be in the format major.minor.patch.	String
     Description	No	An optional description of the ruleset.	String

  5. Optional: For API rulesets, you can add one or more tags to your ruleset by clicking Add, and completing the tag Name and Description.
     Adding matching tags to your rulesets and APIs, means that validation scans can preselect which rulesets to use for the scan. However, you can override this preselection with rulesets of your choice. For information about how to add tags to APIs, see Adding tags to an API.
  6. Click Next, and add an initial rule to your ruleset.
  7. Provide the following Rule info details.

     Property label	Required	Description	Data type
     Title	Yes	A short descriptive name for the rule.	String
     Name	Yes	An auto-generated, sluggified, string that is based on the title. It is not editable.	String
     Description	Yes	A description of the rule.	String
     Message	No	Provide a message to help users understand what the goal of the rule is. If no message is provided, the value of the Description property is used for the message output of the validation scan.	String
     Severity	Yes	Select a severity level from the following options: error warn info hint off error is selected by default.	String

  8. In the Given section, specify one or more values for the parts of the API or product document to target. To add more values, click Add. Values must be written in JSONPath.
  9. In the Then section, specify the function type and options that will be used to evaluate the target values in the API or product document. Write this section in YAML syntax.
     In the following API rule example, for a Given value of $ (which means root level of the document), the Then section uses the Spectral core truthy function to check that the info.contact property value is not false, "", 0, null, or undefined.

     - field: info.contact
       function: truthy

     The Then section can also contain a list of functions to be applied to the Given part of the document. In the following API rule example, for a Given value of $.info.version (which refers to the version property inside the info property at the root level of the document), the Then section uses both the truthy function, and the Spectral core pattern function that checks that the info.value matches the regex expression that is given by functionOptions.match.

     - function: truthy
     - function: pattern
       functionOptions:
         match: "^[0-9]+.[0-9]+.[0-9]+(-[a-z0-9+.-]+)?"

     For a complete list of the Spectral core functions that you can use in your custom API rules, along with examples of these functions, see https://docs.stoplight.io/docs/spectral/cb95cf0d26b83-core-functions.
  10. Click Create to create your draft ruleset.
      Your draft ruleset opens in design form view. Note that you can switch to the OpenAPI YAML source view by clicking the Source icon . To return to the design form view, click the Form icon .
  11. You now have the following options:
      • You can continue to edit your ruleset. For example, you can add more rules by clicking the Create rule icon alongside Rules in the navigation pane. Remember to click Save when you finish editing.
      • If you don't want to edit your ruleset further now, click Governance in the breadcrumb trail to return to the Governance overview page.
• To import an existing API or product ruleset, complete the following steps. Remember that for API rulesets, the rules in your imported ruleset can contain only built-in Spectral core functions, as defined in https://docs.stoplight.io/docs/spectral/cb95cf0d26b83-core-functions.
  1. In the side menu bar, click Governance.
     The Governance page is displayed.
  2. If you want to create an API ruleset, click the API tab. If you want to create a product ruleset, click the Product tab.
     The manage rulesets page is displayed.
  3. In the Global rulesets section, click Add > Import.
     The Import ruleset wizard opens.
  4. Drag a file into the Upload file box, or click in the Upload file box to select a file to upload. The maximum file size is 100 kb, and the supported file types are YAML, YML, and JSON.
  5. Click Next.
  6. Edit the Ruleset info details as required, and click Import.
     Your draft ruleset opens in design form view. Note that you can switch to the OpenAPI YAML source view by clicking the Source icon . To return to the design form view, click the Form icon .
  7. You now have the following options:
     • You can continue to edit your ruleset. For example, you can add more rules by clicking the Create rule icon alongside Rules in the navigation pane. Remember to click Save when you finish editing.
     • If you don't want to edit your ruleset further now, click Governance in the breadcrumb trail to return to the Governance overview page.
• To create an API or product ruleset by using the toolkit CLI, complete the following steps.
  1. Create a JSON file that contains the new ruleset.

     The following JSON shows the contents of an example API document ruleset file:

     {
         "name": "short-draft-ootb",
         "title": "short-draft-ootb",
         "description": "short ruleset",
         "ruleset_type": "global-custom",
         "tags": [
           {
             "name": "general",
             "description": "general work"
           }
         ]
         "rules": [
           {
             "name": "sec-array-boundaries-2",
             "description": "Array size should be limited to mitigate resource exhaustion attacks.\nThis can be done using `maxItems` and `minItems`, like in the example\nbelow.\n\n```\nLimited:\n  type: array\n  maxItems: 10\n  items:\n    type: string\n    format: date\n```\n\nYou should ensure that the schema referenced in  `items` is constrained too.\n\nIf you delegate input validation to a library or framework,\nbe sure to test it thoroughly and ensure that it verifies `maxItems`.",
             "message": "Schema of type array must specify maxItems and minItems. {{path}} {{error}}",
             "formats": [
               "oas3"
             ],
             "severity": "warn",
             "recommended": true,
             "given": [
               "$..[?(@.type==\"array\")]"
             ],
             "then": [
               {
                 "field": "maxItems",
                 "function": "defined"
               }
             ]
           }
         ]
       }

     The following JSON shows the contents of an example product document ruleset file:

     {
       "type": "ruleset",
       "ruleset_type": "custom",
       "api_version": "2.0.0",
       "id": "dbb5f400-e707-412e-b081-ac36f5afbbb9",
       "name": "test-product",
       "title": "Test Product",
       "description": "",
       "ruleset_version": "1.0.0",
       "ruleset_state": "draft",
       "ruleset_format_type": "2",
       "rule_urls": [
         "https://my.manager.com/governance/orgs/myorg/rulesets/1.0.0-test-product/rules/ca6ef7d9-a503-498e-8f53-4e3aa35d086b"
       ],
       "created_at": "2024-05-22T17:19:02.820Z",
       "updated_at": "2024-05-22T17:24:59.000Z",
       "url": "https://my.manager.com/governance/orgs/myorg/rulesets/dbb5f400-e707-412e-b081-ac36f5afbbb9",
       "rules": [
         {
           "api_version": "2.0.0",
           "id": "ca6ef7d9-a503-498e-8f53-4e3aa35d086b",
           "name": "subscribe",
           "version": "1.0.0",
           "title": "subscribe",
           "description": "subscribe enabled",
           "message": "subscribe not enabled",
           "given": [
             "$.visibility.subscribe.enabled"
           ],
           "severity": "error",
           "created_at": "2024-05-22T17:19:02.000Z",
           "updated_at": "2024-05-22T17:24:59.000Z",
           "url": "https://my.manager.com/governance/orgs/myorg/rulesets/1.0.0-test-product/rules/ca6ef7d9-a503-498e-8f53-4e3aa35d086b",
           "then": [
             {
               "function": "pattern",
               "functionOptions": {
                 "notMatch": "/true"
               }
             }
           ]
         }
       ]
     }
     

  2. Log in to the toolkit as an Admin.
     For example:

     apic login --server mgmt_endpoint_url --username admin --password password --realm admin/identity_provider

     You can determine which identity provider to use in the --realm parameter by entering the following command to see a list of all available identity providers (you do not need to be logged in to use this command):

     apic identity-providers:list --scope admin --server mgmt_endpoint_url --fields title,realm

     For example:

     apic identity-providers:list --scope admin --server myserver.com --fields title,realm
     total_results: 2
     results:
       - title: Cloud Manager User Registry
         realm: admin/default-idp-1
       - title: Corporate LDAP user registry
         realm: admin/corporate-ldap

     The title value should enable you to determine which identity provider to use; you can then copy the corresponding --realm parameter directly from the displayed realm value. For any identity providers that were created by your administrator after API Connect was installed, the names will have been determined at creation time. The default Cloud Manager Local User Registry for login as a member of the cloud administration organization is default-idp-1.

     For full details of the apic login command, see Logging in to a management server.

  3. Run the rulesets:create toolkit command in governance mode:

     apic -m governance rulesets:create --org <target_org> --server <server_url> RULESET_FILE

     Where:

     • <target_org> is the name of the organization that owns the new ruleset.
     • <server_url> is the management server URL that you use for logging in to the toolkit.
     • RULESET_FILE is the path and file name of the JSON file that contains the ruleset.

What to do next

When you finish editing your ruleset, you can publish it to your provider organizations. Click the options menu icon either next to the ruleset that you want to publish, or from within the ruleset viewer. Select Publish, and then click Publish again to confirm. The status of your ruleset changes from Draft to Published, and can now be used to validate API and product documents. For more information, see Validating an API document by using governance.

You can also use a published ruleset to validate an API or product document in the Cloud Manager. Click Validate, upload a document file to validate, and then select the rulesets and rules that you want to use for the validation. If the API that you want to validate includes a tag that has a matching tag in one or more rulesets, then those rulesets are automatically selected for the scan. However, you can edit the ruleset selection to your requirements. The results of the validation are displayed in a scorecard.

Note:

• After a ruleset is published, the ruleset information and rules can no longer be edited. If you need to update this information, you must create a new version by clicking the options menu icon either next to the ruleset that you want to edit, or from within the ruleset viewer, and selecting Save as new ruleset.
• By default, rulesets are published to all of your provider organizations. If you want to change which provider organizations can use your rulesets, you must edit the visibility after publishing.

If you want to change the visibility of your ruleset, click the options menu icon either next to the ruleset that you want to edit, or from within the ruleset viewer. Then click Edit visibility, and select from the following visibility options:

• Private - the ruleset is not visible and cannot be used by any provider organization.
• Public - the ruleset is visible and can be used by all provider organizations.
• Custom - the ruleset is visible to and can be used by only the provider organizations that are designated by you.

Click Save to confirm your visibility option.