Verrazzano Enterprise Container Platform – Verrazzano Application Traits

Docs: About Verrazzano Traits

Mon, 01 Jan 0001 00:00:00 +0000

Traits customize Component workloads and generate related resources during deployment. Verrazzano provides several Traits, for example IngressTrait and MetricsTrait. The platform extracts Traits contained within an ApplicationConfiguration during deployment. This processing is similar to the extraction of workload content from Component resources. Note that for some Kubernetes resources, the oam-kubernetes-runtime operator may need to be granted create permission.

A Kubernetes operator, for example verrazzano-application-operator, processes these extracted Traits and may create additional related resources or may alter related workloads. Each Trait implementation will behave differently.

The following sample shows an IngressTrait applied to a referenced Component.

apiVersion: core.oam.dev/v1alpha2
kind: ApplicationConfiguration
...
spec:
  components:
    - componentName: example-component
      traits:
        - trait:
            apiVersion: oam.verrazzano.io/v1alpha1
            kind: IngressTrait
            spec:
              rules:
                - paths:
                    - path: "/greet"

Each Trait type optionally can have an associated TraitDefinition. This provides the platform with additional information about the Trait’s schema and workloads to which the Trait can be applied. A TraitDefintion is typically provided by the platform, not an end user.

The Verrazzano platform provides several Trait definitions and implementations:

Docs: IngressTrait

Mon, 01 Jan 0001 00:00:00 +0000

The IngressTrait custom resource contains the configuration of host and path rules for traffic routing to an application. Here is a sample ApplicationConfiguration that specifies an IngressTrait. To deploy an example application that demonstrates this IngressTrait, see Hello World Helidon.

apiVersion: core.oam.dev/v1alpha2
kind: ApplicationConfiguration
metadata:
  name: hello-helidon-appconf
  namespace: hello-helidon
  annotations:
    version: v1.0.0
    description: "Hello Helidon application"
spec:
  components:
    - componentName: hello-helidon-component
      traits:
        - trait:
            apiVersion: oam.verrazzano.io/v1alpha1
            kind: IngressTrait
            metadata:
              name: hello-helidon-ingress
            spec:
              rules:
                - paths:
                    - path: "/greet"
                      pathType: Prefix

In the sample configuration, the IngressTrait hello-helidon-ingress is set on the hello-helidon-component application component and defines an ingress rule that configures a path and path type. This exposes a route for external access to the application. Note that because no hosts list is given for the IngressRule, a DNS host name is automatically generated.

For example, with the sample application configuration successfully deployed, the application will be accessible with the path specified in the IngressTrait and the generated host name.

$ HOST=$(kubectl get gateways.networking.istio.io hello-helidon-hello-helidon-gw -n hello-helidon -o jsonpath={.spec.servers[0].hosts[0]})
$ echo $HOST
hello-helidon-appconf.hello-helidon.11.22.33.44.nip.io

$ curl -sk -X GET https://${HOST}/greet

Load balancer session affinity is configured using an HTTP cookie in a destination rule. Here is an updated sample ApplicationConfiguration that includes a destination rule with an HTTP cookie.

apiVersion: core.oam.dev/v1alpha2
kind: ApplicationConfiguration
metadata:
  name: hello-helidon-appconf
  namespace: hello-helidon
  annotations:
    version: v1.0.0
    description: "Hello Helidon application"
spec:
  components:
    - componentName: hello-helidon-component
      traits:
        - trait:
            apiVersion: oam.verrazzano.io/v1alpha1
            kind: IngressTrait
            metadata:
              name: hello-helidon-ingress
            spec:
              rules:
                - paths:
                    - path: "/greet"
                      pathType: Prefix
                - destination:
                    httpCookie:
                      name: sessioncookie
                      path: "/"
                      ttl: 600

Additionally, an authorization policy limiting access to specific request principals and optionally predicated on additional conditions, can be specified for a path. Request for the path will be limited to matching request principals that meet the defined conditions, otherwise the request will be denied.

apiVersion: core.oam.dev/v1alpha2
kind: ApplicationConfiguration
metadata:
  name: hello-helidon-appconf
  namespace: hello-helidon
  annotations:
    version: v1.0.0
    description: "Hello Helidon application"
spec:
  components:
    - componentName: hello-helidon-component
      traits:
        - trait:
            apiVersion: oam.verrazzano.io/v1alpha1
            kind: IngressTrait
            metadata:
              name: hello-helidon-ingress
            spec:
              rules:
                - paths:
                    - path: "/greet"
                      pathType: Prefix
                      authorizationPolicy:
                        rules:
                          - from:
                              requestPrincipals:
                                - "*"
                              when:
                                - key: request.auth.claims[realm_access][roles]
                                  values:
                                    - "customer"

Use the following rules related to the host name:

If you provide a host name, then you have an option to provide a certificate. If you do not provide a certificate, then Verrazzano generates one for you.
If you provide a certificate, the TLS secret for that certificate must be in the istio-system namespace.
If you provide a certificate, then you must provide a host name.
If you do not provide either a host name or a certificate, then Verrazzano generates them for you.

Docs: LoggingTrait

Mon, 01 Jan 0001 00:00:00 +0000

The LoggingTrait custom resource contains the configuration for an additional logging sidecar with a custom image and Fluentd configuration file. Here is a sample ApplicationConfiguration that includes a LoggingTrait. To deploy an example application with this LoggingTrait, replace the ApplicationConfiguration of the ToDo-List example application with the following sample.

apiVersion: core.oam.dev/v1alpha2
kind: ApplicationConfiguration
metadata:
  name: todo-appconf
  namespace: todo-list
  annotations:
    version: v1.0.0
    description: "ToDo List example application"
spec:
  components:
    - componentName: todo-domain
      traits:
        - trait:
            apiVersion: oam.verrazzano.io/v1alpha1
            kind: LoggingTrait
            metadata:
              name: logging-trait-example
              namespace: todo-list
            spec:
              loggingImage: fluent/fleuntd-example-image # Replace with custom Fluentd Image
              loggingConfig: |-
                # Replace with Fluentd config file
                <match **>
                @type stdout
                </match>
    - componentName: todo-jdbc-configmap
    - componentName: todo-mysql-configmap
    - componentName: todo-mysql-service
    - componentName: todo-mysql-deployment

In this sample configuration, the LoggingTrait logging-trait-example is set on the todo-domain application component and defines a logging sidecar with the given Fluentd image and configuration file. This sidecar will be attached to the component’s pod and will gather logs according to the given Fluentd configuration file. In order for the Fluentd DaemonSet to collect the custom logs, the Fluentd configuration file needs to direct the logs to STDOUT, as demonstrated in the previous example.

For example, when the ToDo-List example ApplicationConfiguration is successfully deployed with a LoggingTrait, the tododomain-adminserver pod will have a container named logging-stdout.

$ kubectl get pods tododomain-adminserver -n todo-list -o jsonpath='{.spec.containers[*].name}'
  ... logging-stdout ...

In this example, the logging-stdout container will run the image given in the LoggingTrait and a ConfigMap named logging-stdout-todo-domain-domain will be created with the custom Fluentd configuration file.

Docs: MetricsTrait

Mon, 01 Jan 0001 00:00:00 +0000

The MetricsTrait custom resource contains the configuration information needed to enable metrics for an application component. Component workloads configured with a MetricsTrait are set up to emit metrics through an endpoint that are scraped by a given Prometheus deployment. Here is a sample ApplicationConfiguration that specifies a MetricsTrait. To deploy an example application that demonstrates a MetricsTrait, see Hello World Helidon.

Note that if an ApplicationConfiguration does not specify a MetricsTrait, then a default MetricsTrait will be generated with values appropriate for the workload type.

apiVersion: core.oam.dev/v1alpha2
kind: ApplicationConfiguration
metadata:
  name: hello-helidon-appconf
  namespace: hello-helidon
  annotations:
    version: v1.0.0
    description: "Hello Helidon application"
spec:
  components:
    - componentName: hello-helidon-component
      traits:
        - trait:
            apiVersion: oam.verrazzano.io/v1alpha1
            kind: MetricsTrait
        - trait:
            apiVersion: oam.verrazzano.io/v1alpha1
            kind: IngressTrait
            metadata:
              name: hello-helidon-ingress
            spec:
              rules:
                - paths:
                    - path: "/greet"
                      pathType: Prefix

In the sample configuration, a MetricsTrait is specified for the hello-helidon-component application component.

With the sample application configuration successfully deployed, you can query for metrics from the application component.

$ HOST=$(kubectl get ingress \
     -n verrazzano-system vmi-system-prometheus \
     -o jsonpath={.spec.rules[0].host})
$ echo $HOST

prometheus.vmi.system.default.<ip>.nip.io

$ VZPASS=$(kubectl get secret \
     --namespace verrazzano-system verrazzano \
     -o jsonpath={.data.password} | base64 \
     --decode; echo)
$ curl -sk \
    --user verrazzano:${VZPASS} \
    -X GET https://${HOST}/api/v1/query?query=vendor_requests_count_total

{"status":"success","data":{"resultType":"vector","result":[{"metric":{"__name__":"vendor_requests_count_total","app":"hello-helidon","app_oam_dev_component":"hello-helidon-component","app_oam_dev_name":"hello-helidon-appconf","app_oam_dev_resourceType":"WORKLOAD","app_oam_dev_revision":"hello-helidon-component-v1","containerizedworkload_oam_crossplane_io":"496df78f-ef8b-4753-97fd-d9218d2f38f1","job":"hello-helidon-appconf_default_helidon-logging_hello-helidon-component","namespace":"helidon-logging","pod_name":"hello-helidon-workload-b7d9d95d8-ht7gb","pod_template_hash":"b7d9d95d8"},"value":[1616535232.487,"4800"]}]}}