UCS Microservice Compliance#

UCS specification contains a set of rules or guidelines that a microservice must follow to make sure the services are UCS Compliant. These rules or guidelines are meant to make sure a microservice is secure and production-ready.

When building a microservice the UCS Microservice Builder CLI performs checks to decide if the microservice is following these compliance guidelines. Some of these checks are fully automated, some are partially automated, while the remaining are manual i.e the microservice developers must run the specified checks manually and report the results.

View Microservice Compliance - CLI Tools#

The service info command of the CLI Tools can be used to view the compliance information. By default a summary of the report is printed. To view a detailed report add --show-compliance-details to the command line:

$ ucf_ms_builder_cli service info -n ucf.svc.myservice --show-compliance-details
name: ucf.svc.myservice
...
Compliance Info:
---------------------
Report Generated on 2022-11-08 12:56:36 (UTC) using MSBuilder v2.0.0
Development compliance (Mandatory) 65.38%
Development compliance (Optional) 33.33%

+---------+---------------------------------------------------------------------------------+-------------+--------+
|   ID    | Description                                                                     |  Mandatory  |  Pass  |
+=========+=================================================================================+=============+========+
| DEV-001 | K8S Service resource name must follow RFC 1035 convention                       |      Y      |   Y    |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-002 | Containers shall not use root permissions                                       |      Y      |   Y    |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-003 | Containers shall not use host network                                           |      Y      |   Y    |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-004 | Ports shall not clash in one Pod                                                |      Y      |   Y    |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-005 | No hardcoded IPs or service names                                               |      Y      |   N    |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-006 | Endpoint definition files are available for each endpoint                       |      Y      |   Y    |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-007 | Endpoint definitions validation                                                 |      Y      |   Y    |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-008 | Parameter's format validation                                                   |      Y      |   Y    |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-009 | Liveness and readiness probes for containers                                    |      Y      |   Y    |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-010 | Helm chart must pass Helm lint test                                             |      Y      |   Y    |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-011 | MS Helm charts must not include any secrets like usernames, passwords, API keys |      Y      |   N    |
|         | in plain-text format                                                            |             |        |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-012 | Containers must not use floating tags like latest, head                         |      Y      |   N    |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-013 | Components and manifest must pass JSON schema validation                        |      Y      |   Y    |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-014 | MS containers must not fetch and install packages at deploy time                |      Y      |   N    |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-015 | At least one test must be implemented                                           |      Y      |   Y    |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-016 | Pods shall not use local directory path or host mount                           |      Y      |   Y    |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-017 | MS version updates must follow semantic versioning                              |      Y      |   N    |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-018 | MS documentation must follow the MS documentation guidelines                    |      Y      |   N    |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-019 | MS must be able to handle situations where dependent MS restart                 |      Y      |   N    |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-020 | MS must be able to gracefully handle situations where dependent MS crash / are  |      Y      |   N    |
|         | unresponsive                                                                    |             |        |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-022 | Testapp shouldn't have '.' in the name                                          |      Y      |   Y    |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-023 | Microservice shouldn't have '_' in the name; instead use '-'                    |      Y      |   Y    |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-024 | Only accepted (key: value) pairs should be present in the manifest              |      Y      |   Y    |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-025 | Microservice must have at least one ingress or egress endpoint                  |      Y      |   Y    |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-027 | Microservice must read secrets from files                                       |      Y      |   N    |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-101 | Log information to stdout or stderr                                             |      N      |   N    |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-102 | Parameter naming should follow camelCase                                        |      N      |   Y    |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-103 | Apply CPU and memory limits to pods                                             |      N      |   N    |
+---------+---------------------------------------------------------------------------------+-------------+--------+
| DEV-104 | If custom metrics need to be used to scale a microservice, it must implement    |      N      |   N    |
|         | metrics endpoint & add info to the metrics section.                             |             |        |
+---------+---------------------------------------------------------------------------------+-------------+--------|
| DEV-105 | Microservices must instrument their applications using OpenTelemetry SDK        |      N      |   N    |
+---------+---------------------------------------------------------------------------------+-------------+--------+

Alternatively, the UCS Application Builder CLI tool can be used as well:

$ ucf_app_builder_cli service info -n ucf.svc.myservice --show-compliance-details

View Microservice Compliance - UCS Studio#

UCS Microservice Compliance Rules#

This section describes the set of UCS compliance rules. Every compliance rule has an ID to identify it by.

Summary#

In the following table

MSB indicates the test will be run by UCS Microservice Builder CLI
Developer indicates test must be run manually by microservice developer

Compliance ID	Description	Mandatory	Compliance performed by
DEV-001	K8S Service resource name must follow RFC 1035 convention	Y	MSB
DEV-002	Containers shall not use root permission	Y	MSB
DEV-003	Containers shall not use host network	Y	MSB
DEV-004	Ports shall not clash in one Pod	Y	MSB
DEV-005	No hardcoded IPs or service names	Y	Developer
DEV-006	Endpoint definition files are available for each endpoint	Y	MSB
DEV-007	Endpoint definitions validation	Y	MSB
DEV-008	Parameter’s format validation	Y	MSB
DEV-009	Liveness and readiness probes for containers	Y	MSB
DEV-010	Helm chart must pass Helm lint test	Y	MSB
DEV-011	MS Helm charts must not include any secrets like usernames, passwords, API keys in plain-text format	Y	Developer
DEV-012	Containers must not use floating tags like `latest`, `head`	Y	MSB
DEV-013	Components and manifest must pass JSON schema validation	Y	MSB
DEV-014	MS containers must not fetch and install packages at deploy time	Y	Developer
DEV-015	At least one test must be implemented	Y	MSB
DEV-016	Pods shall not use local directory path or host mount, must use through PV/PVCs	Y	MSB
DEV-017	MS version updates must follow semantic versioning	Y	MSB & Developer
DEV-018	MS documentation must follow the MS documentation guidelines	Y	MSB & Developer
DEV-019	MS must be able to handle situations where dependent MS restart	Y	Developer
DEV-020	MS must be able to gracefully handle situations where dependent MS crash / are unresponsive	Y	Developer
DEV-022	Name of a test shouldn’t have period (`.`) in the name	Y	MSB
DEV-023	Name of the service shouldn’t have an underscore (`_`) in the name	Y	MSB
DEV-024	Check for unrecognized keys in the manifest file	Y	MSB
DEV-025	Microservice must have at least one ingress or egress endpoint	Y	MSB
DEV-027	Microservice must read secrets from files	Y	Developer
DEV-101	Log information to stdout or stderr	N	Developer
DEV-102	Parameter naming should follow `camelCase`	N	MSB
DEV-103	Apply CPU and memory limits to pods	N	MSB
DEV-104	If custom metrics need to be used to scale a microservice, it must implement metrics endpoint & add info to the metrics section	N	Developer
DEV-105	Microservices must instrument their applications using OpenTelemetry SDK	N	Developer

Details#

DEV-001 - Service Name

Kubernetes Service Resource names in UCS microservices must follow the RFC 1035 DNS label standard. This is a requirement of Kubernetes itself. This means that the name must:

contain at most 63 characters

contain only lowercase alphanumeric characters or ‘-’

start with an alphabetic character

end with an alphanumeric character

The UCS Microservice Builder CLI tool will check all Kubernetes service resources in the UCS microservice against the above criteria.

DEV-002 - Containers shall not use root permissions

Non-root containers must be used in UCS microservices. This can be done by adding USER directive in the container’s Dockerfile

PodSecurityContext must be set on the deployment with minimal permissions as necessary.

runAsUser must be set

privileged must be false / unset

The UCS Microservice Builder CLI tool will use docker / helm commands to check if the above guidelines are being followed

DEV-003 - No Host network

Pods in a UCS microservice must not use host network. This can be done by setting hostNetwork to false or leaving it unset in the pod spec.

The UCS Microservice Builder CLI tool will inspect all workload resources in an UCS microservice for presence of hostNetwork: True in pod spec.

DEV-004 - Ports shall not clash in one pod

No two containers specified in a UCS microservice pod shall expose the same port.

The UCS Microservice Builder CLI tool will check pod specification to check for port clashes

DEV-005 - No Hardcoded IP Addresses or service-names

UCS microservices shall not hardcode IP addresses or service names to connect to other microservices. They must use the egress endpoint and $egress placeholders which are substituted with connected ingress endpoint details by the UCS app builder tool.

Since it is difficult to check if a string in the helm chart is an IP address/service name, the UCS Microservice Builder CLI tool will not have a check for this rule. Developers must make sure to follow this rule themselves.

DEV-006 - Endpoint definition files are available for each endpoint

An endpoint definition file must be specified for each ingress and egress endpoint added to the UCS microservice. The file must be added to the endpoints directory and must have the name <endpoint-name>.<ext> where the extension (and the file format) depends on the endpoint scheme.

The UCS Microservice Builder CLI tool will check for presence of endpoint definition files for each ingress/egress endpoint in the manifest.

DEV-007 - Endpoint definitions validation

Each endpoint definition file must follow the specification based on the endpoint scheme. More details on endpoint specifications can be found at UCS Endpoint Schemes.

The UCS Microservice Builder CLI tool will validate each endpoint file against the specification.

DEV-008 - Parameter’s format validation

Parameters should follow the parameters specification part of UCS MS spec.

The UCS Microservice Builder CLI tool will validate if parameter annotations are valid.

DEV-009 - Liveness and readiness probe for containers

Containers in UCS microservices must specify a valid liveness and readiness probe.

The UCS Microservice Builder CLI tool will check if liveness and readiness probes are specified for all containers in the microservice but not if they are correct. It is up to the MS developer to ensure that the probes are working correctly.

DEV-010 - Helm chart must pass helm lint

The helm chart either generated by the UCS Microservice Builder CLI tool or a prebuilt helm chart must pass helm linter.

The UCS Microservice Builder CLI tool will automatically run helm lint on microservice helm chart when building the microservice.

DEV-011 - No hardcoded secrets

Secrets like passwords, API keys must not be hardcoded in the UCS MS. Instead volumeMounts / environment variables created from secrets must be used.

Tools like Kubernetes secret, hashicorp vault must be used.

It is up to the MS developer to follow this guideline correctly.

DEV-012 - Containers must not use floating tags

Container images mentioned in an UCS microservice must not use floating tags like latest, head, etc., since the actual image these tags refer to might change between publish and deploy time. A tag string referring to a fixed version must be used.

The UCS MS builder will perform a limited check that image tags do not consist of known floating tags like latest, head. It is up to the MS developer to make sure a correct fixed version tag is used.

DEV-013 - Components and manifest must pass JSON schema validation

The UCS msbuilder input manifest file must follow the manifest spec. The components used in the manifest must specify component parameters correctly and pass parameter JSON schema validation.

The UCS MS builder will validate the manifest file and parameters for each component in the manifest against the component’s parameter schema.

DEV-014 - MS containers must not fetch and install packages at deploy time

Containers in UCS microservices must not fetch and install packages at deploy time since it will invalidate the CVE scans for containers.

It is up to the MS developer to follow this guideline correctly

DEV-015 - At least one test must be implemented

At least one test must be implemented and added to the UCS microservice input manifest.

The UCS Microservice Builder CLI tool will check for presence of at least one valid test specification in the input manifest file.

DEV-016 - No local host mounts

Pods in a UCS MS must not directly mount a host path (file or directory) using hostPath volume. UCS microservices must use a PV / PVC along with a provisioner like local-path-provisioner or mdx-local-path-provisioner.

The UCS Microservice Builder CLI tool will check for presence of hostPath volumes in the UCS microservice.

DEV-017 - MS version updates must follow semantic versioning

Updates to a UCS microservice must follow semantic versioning guidelines. Refer to https://semver.org/ for more information.

It is up to the MS developer to correctly follow the semantic versioning guidelines. The UCS Microservice Builder CLI tool will not always be able to detect if a change is backward compatible enhancements / bug fix / backward incompatible update.

DEV-018 - MS documentation must follow UCS MS documentation guidelines

The documentation of a UCS microservice must follow the UCS MS documentation guidelines. The microservice must have:

README.md in a specified format with a specified list of sections
LICENSE.txt with microservice license information along with licenses of any 3rdparty software used
changelog.txt containing list of changes in the current version with respect to the previous version

The ucf_ms_builder_cli service create command can be used to generate a template for the above documents.

The UCS Microservice Builder CLI tool will check for the existence of the above files and if they contain certain sections. However, it is also up to the MS developer to correctly follow the documentation guidelines and specify correct information.

DEV-019 - MS must be able to handle situations where dependent MS restart

UCS microservices must be able to handles situations where dependent microservices in a deployment get restarted. This could happen either because the dependent microservice crashed or a helm upgrade caused it. It is recommended that:

The microservice should keep on trying reconnection to the dependent microservices OR
Exit gracefully so that Kubernetes will keep restarting the microservice till it is able to connect to dependent microservices and function properly

The UCS microservice should NOT get stuck / deadlocked in such a situation.

It is up to the MS developer to follow this guideline correctly. A test maybe implemented to simulate this situation.

DEV-020 - MS must be able to handle situations where dependent MS crash / become unresponsive / return incorrect results

UCS microservices must be able to handle situations where dependent microservices in a deployment crash or become unresponsive or return incorrect results. It is recommended that:

The microservice should keep on trying reconnection to the dependent microservices OR
Exit gracefully so that Kubernetes will keep restarting the microservice till it is able to connect to dependent microservices and function properly

Log the exact cause for exiting so that it is easy to debug the issue

The UCS microservice should NOT get stuck / deadlocked in such a situation.

It is up to the MS developer to follow this guideline correctly. A test may be implemented to simulate this situation.

DEV-022 - Test app shouldn’t have . in the name

Test apps specified in the manifest file must not have a dot . in the name.

The UCS Microservice Builder CLI tool will check the test names in the manifest for this condition

DEV-023 - Microservice shouldn’t have _ in the name

Microservice shouldn’t have _ in the name. Instead use - for spacing words

The UCS Microservice Builder CLI tool will check the microservice name during build time.

DEV-024 - Only accepted (key: value) pairs should be present in the manifest

The input manifest file must only contain accepted key-value pairs. No extraneous parameters are allowed.

The UCS Microservice Builder CLI tool will check manifest file contents for extraneous parameters.

DEV-025 - Microservice must have at least one ingress or egress endpoint

Microservice must have at least one ingress or egress endpoint. A microservice with no endpoints is not allowed.

The UCS Microservice Builder CLI tool will check the manifest for at least one endpoint.

DEV-027 - Microservice must read secrets from files

Microservice must read secrets from files.

It is up to the MS developer to follow this guideline correctly.

DEV-101 - Log information to stdout or stderr

Containers in UCS microservices must log information to stdout / stderr.

It is up to the MS developer to follow this guideline correctly

DEV-102 - Parameter naming should follow camelCase

Parameter names should start with a lower case and follow the camelCase naming convention.

The UCS Microservice Builder CLI tool will partially check if parameter names follow camelCase and log a warning if not.

DEV-103 - Apply CPU and memory limits to pods

Pods in UCS microservices must apply CPU and memory limits using resources parameters in containers section.

The UCS Microservice Builder CLI tool will check if resource limits have been specified and log a warning if not.

DEV-104 - If custom metrics need to be used to scale a microservice, it must implement metrics endpoint & add info to the metrics section.

Information added to the metrics section is used by the UCS Application Builder to configure Prometheus server to scrape metrics from the microservice. This information including the list of metrics and their details is also viewable by the application developers. This can be used to create configuration for Horizontal autoscaling.

It is up to the MS developer to follow this guideline correctly.

DEV-105 - Microservices must instrument their applications using OpenTelemetry SDK

Microservices must instrument their applications using OpenTelemetry SDK. This is to decouple the application from the instrumentation backend and make it vendor neutral.

It is up to the MS developer to follow this guideline correctly.