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

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 oso custom values.yaml file 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 oso custom values.yaml file:
    1. Global Labels(allResources): These labels are attached to all the Kubernetes resources. This is depicted as TYPE1 in the following sample oso 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 oso 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 oso 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
  • 23_4_common_pod

Prerequisites

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

Table 3-2 OSO Configuration Parameter

Parameter Description Details
OSO-RELEASE-NAME

This is a mandatory 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

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

serviceAccountNameAlertMgr

This is a mandatory parameter.

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

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

Example:
# Service account for Alertmanagers
  serviceAccountNameAlertMgr: "oso-alm"

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

Data Type: String

Default Value:""

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

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/23_4_common_pod

Data Type: String

Default Value: NA

Range: NA

RETENTION_TIME_ALM

This is a mandatory parameter.

Indicates the amount of time to retain the alertmanager data.

Example: 
extraArgs:
    data.retention: 120h

Data Type: String

Default Value: NA

Range: NA

ALM-PV-SIZE

This is a mandatory parameter.

Indicates the size of the persistence volume of alertmanager.

Example: 
persistentVolume:
    enabled: true
    ...  
    size: 2Gi

Data Type: String

Default Value: NA

Range: NA

ALM-STORAGE-CLASS

This is a mandatory parameter.

Indicates the storage class for alertmanager.

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

Data Type: String

Default Value:standard

Range:NA

CONFIGMAP-RELOAD-REPO-ADDRESS

This is a mandatory parameter.

Indicates the docker image repo 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.

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

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

USE-DEFAULT-SVCACCOUNT-ALM

This is a mandatory parameter.

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

Example:
serviceAccounts:
  alertmanager:
    create: false

Data Type: Boolean

Default Value: false

Range: true, false

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

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