Mandatory secrets must be created prior to running the cartridge management scripts or the instance creation script.

The toolkit provides the sample script: $OSM_CNTK/scripts/manage-instance-credentials.sh to create the secrets for you. Refer to the script code to see the naming and internal structure required for each of these secrets.

See the following topics for more details about Kubernetes Secrets:

• Creating Secrets
• Management of Secrets

Optional secrets are dictated by enabling the out-of-the-box configuration. There is some functionality that is pre-configured in OSM cloud native and can be enabled or disabled in the specification files. When the functionality is enabled, these secrets must be created in the cluster before an OSM instance is created.

• If you use OpenLDAP for authentication, OSM cloud native relies on the following secret to have been created:

  project-instance-openldap-credentials

  The toolkit provides a sample script to create these secrets for you ($OSM_CNTK/samples/credentials/manage-osm-ldap-credentials.sh by passing in "-o secret").
• With Credential Store, the secrets hold credentials for external systems that the automation plug-ins access. These secrets are a pre-requisite to running cartridges that rely on this mechanism and must adhere to a naming convention. See "Provisioning Cartridge User Accounts" for more details.
• When SAF is configured, SAF secrets are used. SAF secrets are similar to custom secrets and are declared in a specialized area within the instance specification that feeds into the SAF-specific WDT.

  safConnectionConfig:
    - name: external_system_identifier
      t3Url: t3_url
      secretName: secret_t3_user_pass

OSM cloud native provides a mechanism where WDT metadata can access sensitive data through a custom secret that is created in the cluster and then declared in the configuration. See "Accessing Kubernetes Secrets from WDT Metadata" to familiarize yourself with this process.

This class of secrets are required only if you need secrets for this mechanism.

To use custom secrets with WDT metadata:

1. Add secret usage in the WDT metadata fragment:

   Host: '@@SECRET:authentication-credentials:host@@'
   Port: '@@SECRET:authentication-credentials:port@@'
   ControlFlag: SUFFICIENT
   Principal: '@@SECRET:authentication-credentials:principal@@'
   CredentialEncrypted: '@@SECRET:authentication-credentials:credential@@'

2. Add the secret to the project specification.

   #Custom secrets
   # Multiple secret names can be provided
   customSecrets:
     enabled: true
     secretNames:
      - authentication-credentials

3. Create the secret in the cluster, by using any one of the following methods:
   • Using OSM cloud native toolkit scripts
   • Using a Template
   • Using the Command-line Interface
   In the example metadata shown in step 1, the secret must capture host, port, principal, and credential.

See "Mechanism for Creating Custom Secrets" for details about the methods.

Using Scripts to Create Secrets

Functionality such as OpenLDAP, NFS, and Credential Store that can be enabled or disabled in OSM cloud native relies on pre-requisite secrets to be created. In such cases, the toolkit provides sample scripts that can create the secrets for you. While these scripts are useful for configuring instances quickly in development situations, it is important to remember that they are sample scripts, and not pipeline friendly. These scripts are also essential because when the secret is mandated by OSM cloud native, both the secret name and the secret data are available in the sample script that populates it.

projectName-instanceName-osmcn-cred-mapName

Using a Template

To create custom secrets using a template:

1. Save the secret details into a template file.

   apiVersion: v2
   kind: Secret
   metadata:
    labels:
    weblogic.resourceVersion: domain-v2
    weblogic.domainUID: project-instance
    weblogic.domainName: project-instance
    namespace: project
    name: secretName
   type: Opaque
   stringData:
   password_key: value1
   user_key: value2

2. Run the following command to create the secret:

   kubectl apply -f templateFile

Using the Command-line Interface

kubectl create secret generic secretName \
-n project \
--from-literal=password_key=value1 \
--from-literal=user_key=value2

To deploy cartridge par files, OSM cloud native employs a mechanism using the OSM cloud native toolkit's manage-cartridges.sh script. You can deploy cartridge par files in offline or online modes.

Using a remote repository is the recommended approach as all aspects of an OSM instance, including the cartridge set deployed, remain in source controlled configuration.

cartridges:
  - name: name_of_the_cartridge - Mandatory, (must match the cartridge name in the par file)
    url: URL_of_the_location_where_to_download_the_cartridge_par_file - Mandatory.
    secret: a Kubernetes_secret_in_the_project_namespace - Optional, only required if remote URL server requires authentication.
    params: Commandline_parameters_will_be_passed_to_curl - Optional, user can provide additional parameters like proxy settings for curl.
    version: cartridge version, example 1.0.0.0.0 - Mandatory, cartridge version (must match the cartridge version in the par file)
    default: true|false - Mandatory, set this cartridge as default cartridge or not.
    deploymentState: deployed|fastundeployed - Mandatory, indicate the desired target state of the cartridge

Offline Cartridge Deployment

This deployment mode supports deployment of new cartridges, deployment of new versions of existing cartridges, and redeployment of existing cartridge versions with changes.

For offline cartridge deployment, all managed servers in your environment must be shut down. The script stops running if there are managed servers up and running. Rolling restart of managed servers is not performed for offline deployment.

vi spec_Path/project-instance.yaml

# Change the cluster size to 0

#cluster size
clusterSize: 0

$OSM_CNTK/scripts/upgrade-instance.sh -p project -i instance -s spec_Path

$OSM_CNTK/scripts/manage-cartridges.sh -p project -i instance -s spec_Path -c sync [-o]

Online Cartridge Deployment

This deployment mode supports deployment of new cartridges and deployment of new versions of existing cartridges.

Deploying cartridges in an OSM cloud native environment provides the following key benefits:

• You can deploy the cartridges without needing to isolate OSM from order processing at the JMS/HTTP level.
• You can describe the cartridges for an environment in a declarative fashion.

In online mode, you can deploy cartridges to your OSM cloud native running instance while orders from a cartridge that you deployed earlier are still being processed. To achieve this, you should have a minimum of two managed servers on which your OSM cloud native instance is running. In such an environment, when you deploy cartridges, OSM availability is uninterrupted and ongoing order processing continues.

You use the manage-cartridges.sh script with the -o option to enable online deployment of cartridges. After deploying the cartridges, the script performs a rolling restart of all the managed servers in your environment.

vi spec_Path/project-instance.yaml

# Change the cluster size to a minimum of 2

#cluster size
clusterSize: 2

$OSM_CNTK/scripts/upgrade-instance.sh -p project -i instance -s spec_Path

$OSM_CNTK/scripts/manage-cartridges.sh -p project -i instance -s spec_Path -c sync [-o]

Consider the following when deploying cartridges in online mode:

• If no managed servers are running, a warning is shown that no managed server is up and running and that the deployment mode is switching to offline deployment. The script continues with offline deployment.
• If only one managed server is running, then the script fails to perform the deployment.

The OSM cloud native deployment has two different methods of providing cartridge par files based on the following types of the environment they are being deployed to:

• Open Environments
• Controlled Environments

Deploying Cartridges in Open Environments

Open environments are mostly development and some test environments. To deploy cartridges to a running instance of OSM cloud native in an open environment, you can use any of the following options:

• Local par file
  Run the script as follows:

  $OSM_CNTK/scripts/manage-cartridges.sh -p projectName -i instanceName -s spec_Path -f cartridge_par_file -c parDeploy

• Remote Repository (Unsecured)

  This approach could be suitable for test environments.

  1. Edit the project specification in your file repository to add entries for each cartridge to be deployed:

     ## Unsecured repository
     cartridges:
      - name: OracleComms_OSM_O2A_COMSOM_CSO_Solution
        version: 2.1.2.0.0
        url: http://example.com/Repo/OracleComms_OSM_O2A_COMSOM_CSO_Solution/OracleComms_OSM_O2A_COMSOM_CSO_Solution.par
        default: true
        deploymentState: deployed
      - name: SimpleRabbits
        version: 1.0.0.0.0
        url: http://example.com/Repo/SimpleRabbits/1.0/SimpleRabbits.par
        default: false
        deploymentState: fastundeployed
      - name: SimpleRabbits
        version: 2.0.0.0.0
        url: http://example.com/Repo/SimpleRabbits/2.0/SimpleRabbits.par
        default: true
        deploymentState: deployed

  2. Run the script as follows:

     $OSM_CNTK/scripts/manage-cartridges.sh -p project_name -i instance_name -s spec_path -c sync [-o]

• Remote Repository - Disabling Verification

  To disable host verification:

  1. Pass in the curl -k option as follows.

     Note:

     Disabling the verification on a secured repository is a security risk.

     ## secured repository, disabling host verification
     cartridges:
      - name: OracleComms_OSM_O2A_COMSOM_CSO_Solution
        version: 2.1.2.0.0
        url: http://example.com/Repo/OracleComms_OSM_O2A_COMSOM_CSO_Solution/OracleComms_OSM_O2A_COMSOM_CSO_Solution.par
        default: true
        deploymentState: deployed
        params: -k
      - name: SimpleRabbits
        version: 1.0.0.0.0
        url: http://example.com/Repo/SimpleRabbits/1.0/SimpleRabbits.par
        default: false
        deploymentState: fastundeployed
        params: -k
      - name: SimpleRabbits
        version: 2.0.0.0.0
        url: http://example.com/Repo/SimpleRabbits/2.0/SimpleRabbits.par
        default: true
        deploymentState: deployed
        params: -k

  2. Run the script as follows:

     $OSM_CNTK/scripts/manage-cartridges.sh -p project_name -i instance_name -s specification_path -c sync [-o]

Deploying Cartridges in Controlled Environments

To install cartridges in controlled environments such as UAT, pre-production, and production, use only the declarative approach. Rather than copying the par files into the cartridge management pod, they are "pulled" from a URL.

The cartridge list is defined in the project specification, ensuring that the cartridge load is also under version control.

• Using a Remote Repository

  To use a remote repository to deploy cartridges in a controlled environment:

  1. Edit the project specification in your file repository as follows:

     ## Credentials required
     cartridges:
      - name: OracleComms_OSM_O2A_COMSOM_CSO_Solution
        version: 2.1.2.0.0
        url: http://example.com/Repo/OracleComms_OSM_O2A_COMSOM_CSO_Solution/OracleComms_OSM_O2A_COMSOM_CSO_Solution.par
        default: true
        deploymentState: deployed
        secret: solution_cartridge_secret_name_in_lowercase
      - name: SimpleRabbits
        version: 1.0.0.0.0
        url: http://example.com/Repo/SimpleRabbits/1.0/SimpleRabbits.par
        default: false
        deploymentState: fastundeployed
        secret: solution_cartridge_secret_name_in_lowercase
      - name: SimpleRabbits
        version: 2.0.0.0.0
        url: http://example.com/Repo/SimpleRabbits/2.0/SimpleRabbits.par
        default: true
        deploymentState: deployed
        secret: solution_cartridge_secret_name_in_lowercase

     The secret would contain any authentication credentials required to download the par file from the remote repository. The toolkit relies on the secret having the entries for the username and password set to the appropriate values. These are used by curl.

     An example of creating the secret using kubectl on the command line is as follows:

     kubectl create secret generic solution_cartridge_secret_name_in_lowercase \
      -n project \
      --from-literal=username='remoteRepoUsername' \
      --from-literal=password='remoteRepoPassword'

  2. Run the script as follows:

     ./scripts/manage-cartridges.sh -p project_name -i instance_name \ -s spec_path -c sync [-o]

• Using a Remote Repository - TLS/SSL

  For HTTPS, the SSL certificate of the repository server must be exposed to the cartridge management pod and then passed as a command line parameter -cacertpath_to_repo_server_ssl_certificate to curl. The path_to_repo_server_ssl_certificate is the path within the pod.

  To allow curl access to the SSL certificate within the cartridge management pod:

  1. Obtain the server certificate by running the following command:

     echo quit | openssl s_client -showcerts -servername repo_server_hostname -connect repo_server_url path_to_repo_server_ssl_name.pem

  2. Run the register-certificate.sh script to create a Kubernetes secret that contains the SSL certificate:

     $OSM_CNTK/scripts/register-certificate.sh -p project_name -n secret_name -f path_to_repo_server_ssl_name.pem

  3. Add the following fragment to the project specification to enable the secret to be mounted at the path /etc/ssl/certs/ within the cartridge management pod. The name is the secret_name created in step 2 and type is the file extension of the certificate file:

     certificates:
       - name: secret_name
         type: file_type
      
     #example
     certificates:
       - name: mySecret
         type: pem

  4. Add the parameter --cacert /etc/ssl/certs/secret_name.file_type to the cartridges: params parameter in the project specification:

     cartridges:
      - name: OracleComms_OSM_O2A_COMSOM_CSO_Solution
        version: 2.1.2.0.0
        url: http://example.com/Repo/OracleComms_OSM_O2A_COMSOM_CSO_Solution/OracleComms_OSM_O2A_COMSOM_CSO_Solution.par
        default: true
        deploymentState: deployed
        params: --cacert /etc/ssl/certs/secret_name.file_type

You use Design Studio or build scripts to undeploy (fast undeploy and full undeploy) OSM cartridges.

You can deploy cartridges directly from Design Studio using the Eclipse user interface or headless Design Studio. However, use Design Studio for deploying cartridges in scenarios where there is a lot of churn in the build, deploy and test cycle, but not for production environments. If used in conjunction with the OSM cloud native cartridge management mechanism, then the deployed cartridges become out of sync with what is listed in the source controlled specification file. For this reason, deploying cartridges using Design Studio is not recommended for environments where the specification file is considered the single source of truth for the set of deployed cartridges.

In order to incorporate Design Studio into the larger OSM cloud native ecosystem, you need to have previously taken care of the mapping of the hostname to the Kubernetes cluster or the load balancer as described in "Planning and Validating Your Cloud Environment".