3 Customizing OSO

This chapter provides information about customizing Oracle Communications Operations Services Overlay (OSO) deployment in a cloud native environment.

The OSO deployment is customized by overriding the default values of various configurable parameters in the <custom-value.yaml> files.

3.1 Naming Conventions and Limits

This section provides the naming conventions and limits for OSO containers and labels.

Naming Conventions and Limits for Containers

OSO supports customization of container names using custom prefix and suffix. Currently, the name field supports up to 63 characters (including the custom prefix, custom suffix, and default fixed name).

Note:

  • The maximum length of default fixed names is 17.
  • To avoid name truncation, limit the number of characters in the custom prefix and suffix to match the defined limit.
The following table displays the default fixed names of containers without prefix and suffix:

Table 3-1 Default Fixed Names of Containers

POD Name Fixed Container Name
Prometheus-server(prom-svr)
  • prom-svr-cm-r
  • prom-svr
Alertmanager(prom-alm)
  • prom-alm
  • prom-alm-cm-r
You can use the following values in the ocoso_csar_24_3_1_0_0_prom_custom_values.yaml and ocoso_csar_24_3_1_0_0_alm_custom_values.yaml files to add the custom prefix and suffix to container names:
global:
# provide the prefix and suffix to be added to k8Resources
  k8Resource:
    container:
      prefix:
      suffix:

Naming Conventions and Limits for Labels

  1. OSO supports custom labels for Kubernetes resources. It provides three types of label definitions that must be configured in the ocoso_csar_24_3_1_0_0_prom_custom_values.yaml and ocoso_csar_24_3_1_0_0_alm_custom_values.yaml files:
    1. Global Labels(allResources): These labels are attached to all the Kubernetes resources. This is depicted as TYPE1 in the following sample ocoso_csar_24_3_1_0_0_prom_custom_values.yaml file.
    2. LB and NON-LB TYPE label: These labels are attached to LoadBalancer and non-LoadBalancer type deployments, statefulsets, and services. This is depicted as TYPE2 in the following sample ocoso_csar_24_3_1_0_0_prom_custom_values.yaml file.
    3. Service specific label: These labels are attached to each service in their specific service-label metadata sections and can be used to uniquely label services, regardless of them being LoadBalancer or non-LoadBalancer.

      Note:

      Prometheus and Alertmanager have their own set of service-specific labels.
    You can use the following values in the ocoso_csar_24_3_1_0_0_prom_custom_values.yaml file to provide custom labels for Kubernetes resources:
    customExtension:
# TYPE1 Label
    allResources:
      labels: {}
# TYPE2 Labels  
    lbServices:
      labels: {}
 
    nonlbServices:
      labels: {}
 
    lbDeployments:
      labels: {}
 
    nonlbDeployments:
      labels: {}
 
    lbStatefulSets:
      labels: {}
..

    Note:

    You must be well aware of the naming guidelines while labeling the resources. For more information on Helm naming guidelines, see Helm Labels and Annotations.

3.2 OSO Configuration Parameters

Overview

This section provides the configuration parameters details that are used to install the OSO CSAR packages manually.

OSO CSAR is packaged with the following open source images:
  • prometheus
  • alertmanager
  • configmapreload
  • 24_3_common_oso

Prerequisites

  • Docker or Podman must be installed.
  • Helm repository must be set up and accessible.

3.2.1 Prometheus Configuration Parameters

This section provides the Prometheus configuration parameters details that are used to install the OSO CSAR packages manually.

Configure ocoso_csar_24_3_1_0_0_prom_custom_values.yaml with the specific values.

Table 3-2 OSO Configuration Parameter

Parameter Description Details
OSO-RELEASE-NAME

This is a conditional parameter.

Indicates the Helm release name for the OSO release.

Example: promsvcname: oso-prom-svralmsvcname: oso-prom-alm

Data Type: String

Default Value: NA

Range: NA

USEASM

This is a conditional parameter.

Indicates if the Aspen Service Mesh (ASM) environment is used or not.

Example: useasm: true

Data Type: Boolean

Default Value: false

Range: true, false

NAMESPACE

This is a mandatory parameter.

Indicates the namespace where OSO will be installed. This value is required in multiple places in the custom values.yaml file.

Example: namespace: ocnf

Data Type: String

Default Value: NA

Range: NA

CLUSTER-NAME

This is a mandatory parameter.

Indicates the name of the cluster where OSO is deployed. This value is required in multiple places in the custom values.yaml file.

Example: clustername: oso-cluster

Data Type: String

Default Value: NA

Range: NA

USE-DEFAULT-SVCACCOUNT-PROM

This is a mandatory parameter.

If default svcaccount is required at cluster scope, then set this parameter to true, else set it to false and create your own svcaccount and configure OSO.

Example:
serviceAccounts:
  prometheus:
    create: false

Data Type: Boolean

Default Value: false

Range: true, false

serviceAccountNamePromSvr

This is a mandatory parameter.

Indicates the ServiceAccount that is to be used by the Prometheus resource.

Users must create ServiceAccount with the required namespace access defined along with the Role or RoleBinding for the Prometheus service.

Example:
# Service account for Prometheus
  serviceAccountNamePromSvr: "oso-prom"

If you do not have a ServiceAccount, then set the USE-DEFAULT-SVCACCOUNT-PROM parameter to true.

Data Type: String

Default Value:""

Range: NA

PROMETHEUS-REPO-ADDRESS

This is a mandatory parameter.

Indicates the docker image repo URL for Prometheus location.

Example: Bastion:5000/occne.io/oso/prometheus

Data Type: String

Default Value: NA

Range: NA

HELM-TEST-IMAGE-REPO-ADDRESS

This is a mandatory parameter.

Indicates the repo URL of the Helm test image location.

Example: 
Bastion:5000/occne.io/occne/24_2_common_pod

Data Type: String

Default Value: NA

Range: NA

CONFIGMAP-RELOAD-REPO-ADDRESS

This is a mandatory parameter.

Indicates the docker image repository URL for configmap-reload location.

Example: 
Bastion:5000/occne.io/oso/configmapreload

Data Type: String

Default Value: NA

Range: NA 

server:
 .......
  ## namespaces to monitor(instead of monitoring all - clusterwide). 
  ##Needed if you want to run without Cluster-admin privileges.
  namespaces:
    - NAMESPACE

This is a mandatory parameter.

If clusterrole is used, comment the namespaces section. If role is used, then give the namespace where OSO is deployed.

Example: 
server:
 .......
  ## namespaces to monitor(instead of monitoring all - clusterwide). 
  ## Needed if you want to run without Cluster-admin privileges.
  ## namespaces:
  ## - NAMESPACE

Data Type: String

Default Value: NA

Range: NA

BEARER_TOKEN

This is a conditional parameter.

Set the Authorization header on every remote write request with the configured bearer token. In this case, it is Cortex Server.

Example:
remote_write 
# bearer_token for cortex server to be configured 
bearer_token: eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.

Data Type: String

Default Value: NA

Range: NA

STORAGE_RETENTION_SIZE_PROM

This is a mandatory parameter.

Indicates the retention size for Prometheus persistence volume.

It should be atleast 85% of the PV size (6.8GB).

Example:
extraArgs:
    storage.tsdb.retention.size: 6.8GB

Data Type: String

Default Value: NA

Range: NA

PROM-PV-SIZE

This is a mandatory parameter.

Indicates the size for the persistence volume of Prometheus.

Example:
persistentVolume:
    enabled: true
    size: 8Gi

Data Type: String

Default Value: NA

Range: NA

PROM-STORAGE-CLASS

This is a mandatory parameter.

Indicates the storage class for Prometheus.

Example:
 persistentVolume:
    enabled: true
    ......
    storageClass: standard

Data Type: String

Default Value:standard

Range: NA

PROM-DATA-RETENTION-DAYS

This is a mandatory parameter.

Indicates the retention days for prometheus persistence volume.

Example:
retention: 7d

Data Type: String

Default Value: NA

Range: NA

OSO_CORTEX_URL

This is a conditional parameter.

Indicates the URL where Prometheus writes metrics data.

Example:
http://<some-ip>:<some-port>/api/prom/push

Data Type: String

Default Value: NA

Range: NA

OSO_REMOTE_WRITE_TIMEOUT

This is a conditional parameter.

Indicates the maximum amount of time Prometheus waits for a response to the remote write request.

Example: 30s

Data Type: String

Default Value: NA

Range: NA

namespaces

This is a conditional parameter.

If you are using external Service Account with namespace specific Role or RoleBinding Access, the namespaces must be configured in Prometheus for extracting the given allowed namespaces.

Uncomment the following lines in the custom values.yaml file and replace ns1 and ns2 with namespaces you want to configure for extracting, in each of the Prometheus jobs.

- job_name: 'oracle-cnc-pod' 
kubernetes_sd_configs: 
- role: pod 
#namespaces: 
# names: 
# - ns1 
# - ns2

You can add more namespaces in the list as per your requirement.

Data Type: String

Default Value: NA

Range: NA

Prefix

Suffix

This is a conditional parameter.

Indicates the prefix and suffix that will be added to K8s Resource names.

Example:
global:
  k8Resource:
    container:
      prefix: oracle1
      suffix: oracle2

Note: Currently, only Containers are configured with prefix and suffix.

Data Type: String

Default Value: NA

Range: NA 

allResources: 
labels: {}

This is a conditional parameter.

Indicates the Global Labels (allResources) that will be attached to all Kubernetes resources.

Example:
allResources:
      labels: 

         env : production

Data Type: String

Default Value: NA

Range: NA 

lbServices:
 labels: {}
nonlbServices:
 labels: {}
lbDeployments:
 labels: {}
nonlbDeployments:
 labels: {}
lbStatefulSets:
 labels: {}

This is a conditional parameter.

Indicates the LB and non-LB TYPE labels that will be attached to the load balancer and non-load balancer type deployments, statefulsets, and services.

Example:
lbServices:
      labels: 

         key1 : value1

    nonlbServices:
      labels: 
         key2 : value2

    lbDeployments:
      labels: 
         key3 : value3

    nonlbDeployments:
      labels: 
         key4 : value4

    lbStatefulSets:
      labels: 
         key5 : value5

Data Type: String

Default Value: NA

Range: NA

annotations: {}

This is a conditional parameter.

Specifies the custom annotations to be added to OSO deployments that are associated to disable the sidecar injections into OSO pods.

Example:
annotations:
    - sidecar.istio.io/inject: "false"

Data Type: Boolean

Default Value: false

Range: true, false 

alertmanagers:
  - kubernetes_sd_configs:
      - role: pod
    # namespace to be configured  
        namespaces:  
          names: {}
    relabel_configs:
    - source_labels: [__meta_kubernetes_namespace]
    # namespace to be configured
      regex: {}

This is a mandatory parameter.

Indicates if this parameter is used to add namespaces for Alertmanager.

Example:
alertmanagers:
  - kubernetes_sd_configs:
      - role: pod
# namespace to be configured 
        namespaces:  
          names: 
          - ns1     
    relabel_configs:
    - source_labels: [__meta_kubernetes_namespace]
      regex: ns1

Data Type: String

Default Value: NA

Range: NA

3.2.2 Alertmanager Configuration Parameters

This section provides the alertmanager configuration parameters details that are used to install the OSO CSAR packages manually.

Configure the ocoso_csar_24_3_1_0_0_alm_custom_values.yaml with the defined values.

Note:

Configure the following parameters using Table 3-2 table:
  • HELM-TEST-IMAGE-REPO-ADDRESS
  • USEASM
  • NAMESPACE
  • CONFIGMAP-RELOAD-REPO-ADDRESS
  • prefix
  • suffix
  • sidecar annotations
  • labels

Table 3-3 OSO Alertmanager Configuration Parameters

Parameter Description Details
OSO-ALM-RELEASE-NAME-alm

This is a mandatory parameter.

Indicates the Helm release name for installing the Alertmanager in OSO release.

Example: oso-a

Data Type: String

Default Value: NA

Range: NA

ALERTMANAGER-REPO-ADDRESS

This is a mandatory parameter.

Indicates the repo URL for alertmanager location.

Example: Bastion:5000/occne.io/oso/alertmanager

Data Type: String

Default Value: NA

Range: NA

RETENTION-TIME-ALM

This is a mandatory parameter.

Indicates the define retention time for alertmanager persistence.

Example: 120h

Data Type: String

Default Value: NA

Range: NA

USE-DEFAULT-SVCACCOUNT-ALM

This is a mandatory parameter.

Indicates if default svcaccount or own svcaccount is required for configuring OSO.

If this value is true, default svcaccount at cluster scope is required. If this value is false, create your own svcaccount and configure OSO

Data Type: Boolean

Default Value: true

Range: true, false

ENABLE_DUAL_STACK

This is a conditional parameter.

Indicates if dual stack support is available for alertmanager.

If this value is true, dual stack support (IPV4 and IPV6) is enabled for alertmanager. If this value is false, dual stack support is not enabled for alertmanger.

Data Type: Boolean

Default Value: true

Range: true, false

ALM-STORAGE-CLASS

This is a conditional parameter.

Indicates the alertmanager storage class configuration.

Data Type: String

Default Value: standard

Range: NA

ALM-PV-SIZE

This is a conditional parameter.

Indicates the size for the alertmanager persistence volume.

Data Type: String

Default Value: 2Gi

Range: NA

annotations: {}

This is a conditional parameter.

Specifies the custom annotations to be added to OSO deployments that are associated to disable the sidecar injections into OSO pods.

Note: This parameter is mandatory if ASM is enabled.

Example:
annotations:
    - sidecar.istio.io/inject: "false"

Data Type: Boolean

Default Value: false

Range: true, false