Skip to content
This repository has been archived by the owner on Nov 2, 2023. It is now read-only.

Latest commit

 

History

History
415 lines (310 loc) · 18.9 KB

adw.md

File metadata and controls

415 lines (310 loc) · 18.9 KB
Raw

Autonomous Data Warehouse Service

Introduction

Autonomous Data Warehouse(ADW) is a managed OCI service built on top of the Oracle Autonomous Database that enables data warehouse deployment in seconds. ADW service is also offered via OCI Service Broker thereby making it easy for applications to provision and integrate seamlessly with ADW.

Plans

Right now we expose a standard plan where the user can specify CPU count and storage size.

OCI User Permission requirement

The OCI user for OCI Service Broker should have permission manage for resource type autonomous-data-warehouse

Sample Policy:

Allow group <SERVICE_BROKER_GROUP> to manage autonomous-data-warehouse in compartment <COMPARTMENT_NAME>

Service Provision Request Parameters

Provisioning a new ADW Service Instance

To provision, an ADW service user needs to provide the following details:

Parameter Description Type Mandatory
name The display name for the ADW instance. string yes
dbName Database Name. string yes
compartmentId The OCI compartment where the ADW instance will be provisioned. string yes
cpuCount Number of CPU cores to have. int yes
storageSizeTBs Size of the DB Storage in Terrabytes. int yes
password ADW Service will pre-provision a DB Admin user when it provisions an ADW instance. The user needs to provide a password to be set for this Admin user.
The OCI ADW service requires the password to satisfy the below rules.
  • The length should be 12 to 18 characters.
  • A password must include an upper case, lower case, and special character.
 string yes
licenseType Use your existing database software licenses(BYOL) or Subscribe to new database software licenses and the Database Cloud Service.
Valid values are:
  • BYOL
  • NEW
.		 string yes
freeFormTags free form tags that are to be used for tagging the ADW instance. object no
definedTags The defined tags that are to be used for tagging the ADW instance. object no

Using an Existing ADW Service Instance

For more information about binding to an existing ADW service instance, see Using an Existing Service Instance.

To attach to an existing ADW service, the user needs to provide the following details. In this case, OCI Service broker will neither provision a new instance nor update/change the existing instance.

Parameter Description Type Mandatory
name The display name for the ADW instance. string yes
ocid The OCID for existing ADW Instance. string yes
provisioning Set provisioning flag value as false. boolean yes

Service Binding Request Parameters

The user needs to pass the following parameters to get the binding details:

Parameter Description Type Mandatory
walletPassword A password to be set for the Oracle wallet that will be created for the application to connect to ADW. This password must
  • Contain more than 8 characters.
  • Contain at least one uppercase, lowercase, and special character
 string yes

Service Binding Response Credentials

Users can create binding to get the credentials to use the ADW. The following files/details will be made available to the user:

Parameter Description Type
ewallet.p12 Oracle Wallet. string
cwallet.sso Oracle wallet with autologin. string
tnsnames.ora Configuration file containing service name and other connection details. string
sqlnet.ora string
ojdbc.properties string
keystore.jks Java Keystore. string
truststore.jks Java trustore. string
user_name Pre-provisioned DB ADMIN Username. string

Examples

Prerequisite

  • Oracle Container Engine for Kubernetes (OKE)/Kubernetes Cluster.
  • OCI Service Broker is installed in the OKE cluster.
  • kubectl to control the OKE Cluster. Please make sure it points to the above OKE Cluster.
  • svcat tool.

OCI Service Broker

Ensure the OCI Service Broker is installed.

svcat get brokers

Sample Output:

           NAME             NAMESPACE                URL                 STATUS  
+-------------------------+-----------+--------------------------------+--------+
  oci-service-broker               http://oci-service-broker:8080   Ready

If no brokers are listed then it means the OCI Service Broker is not installed. Please follow the instructions here to install it first.

Sample files

The sample files for ADW are available under oci-service-broker/samples/adw directory.

Provisioning

A sample Kubernetes resource yaml to provision an ADW instance.

cat oci-service-broker/samples/adw/adw-instance-plain.yaml

Providing password in plain text may not be an idle case. Alternatively, the users can have the password stored in a Kubernetes Secret and have the password passed from that as part of the Provisioning process. Using Secrets to pass in the password is the preferred way.

Please refer Use Secret to pass passwords section for passing the password from secrets.

Creating a new ADW Instance

NOTE: The adw-instance-plain.yaml files contain the compartment OCID in which the user wants to provision the ADW instance. The user needs to update it with their compartment OCID.

kubectl create -f charts/oci-service-broker/samples/adw/adw-instance-plain.yaml

Using an existing ADW Instance

NOTE: The adw-existing-instance.yaml files contain the instance OCID and compartment OCID which the user wants to provision as existing ADW instance. The user needs to update it with their instance OCID and compartment OCID.

kubectl create -f charts/oci-service-broker/samples/adw/adw-existing-instance.yaml

Get instance status

svcat get instances

Output:

NAME NAMESPACE CLASS PLAN STATUS
+----------------+-----------+-------------+----------+--------------+
osb-adw-demo-1 catalog adw-service standard Provisioning

It usually takes 10-15 minutes for the provisioning to complete. Once the ADW instance is provisioned the Status should change to Ready. All other actions on this Service Instances are ignored till the status remain in Provisioning.

NAME NAMESPACE CLASS PLAN STATUS
+----------------+-----------+-------------+----------+--------------+
osb-adw-demo-1 catalog adw-service standard Ready

Binding

Once the ADW Instance is provisioned the applications will require credentials/configuration to connect to the provisioned ADW instance. To do this the user needs to do:

  • Creating a ServiceBinding resource. This will create a Kubernetes secret with the credentials/configurations.
  • The user needs to mount the credentials/configurations into the containers so that application can use this configuration.

A sample Kubernetes resource yaml to create binding:

cat charts/oci-service-broker/samples/adw/adw-binding-plain.yaml

Note:

instanceRef should be same as the instance name for which binding is required.

Creating an ADW ServiceBinding resource

kubectl create -f charts/oci-service-broker/samples/adw/adw-binding-plain.yaml

Get Binding status

svcat get bindings

Output:

NAME NAMESPACE INSTANCE STATUS
+-------------+-----------+----------------+--------+
adw-demo-binding   catalog     osb-adw-demo-1      Ready

When the ServiceBinding request completes successfully the user should see a secret created in the Kuberenetes Cluster with all the credentials/configurations. The name of the secret will be the same as the ServiceBinding name.

kubectl get secrets adw-demo-binding -o yaml

Output:

apiVersion: v1
kind: Secret
type: Opaque
metadata:
  creationTimestamp: 2018-09-20T19:54:02Z
  name: adw-demo-binding
  namespace: catalog
  resourceVersion: "116279449"
  selfLink: /api/v1/namespaces/catalog/secrets/adw-demo-binding
  uid: ec556735-bd0e-11e8-9999-0a580aed122c
data:
  cwallet.sso: b2ZoT05nQUFBQVlBQUFBaEJvblVPWDB2bWJiTHpwZXp
  ewallet.p12: TE1JSVpnekNDR1g4R0NTcUdTSWIzRFFFSEJxQ0NHWEF3Z2hsc0FnR
  keystore.jks: L3UzKzdRQUFBQUlBQUFBQkFBQUFBUUFHYjNKaGEyVjVBQUFCWmU0YnB
  ojdbc.properties: YjNKaFkyeGxMbTVsZEM1M1lXeHNaWFJmYkc5allYUnBiMjQ5S0ZOUFZWSkRSVDBvVFVWVVNFOUVQVVpKVEVVcEtFMUZWRWhQUkY5RVFWUkJQU2hFU1ZKRlExUlBVbGs5Skh0VVRsTmZRVVJOU1U1OUtTa3A=
  sqlnet.ora: VjBGTVRFVlVYMHhQUTBGVVNVOU9JRDBnS0ZOUFZWSkRSU0E5SUNoTlJWUklUMFFnUFNCbWFXeGxLU0FvVFVWVVNFOUVYMFJCVkVFZ1BTQW9SRWxTUlVOVVQxSlpQU0kvTDI1bGRIZHZjbXN2WVdSdGFXNGlLU2twQ2xOVFRGOVRSVkpXU=
  tnsnames.ora: L3UzKzdRQUFBQUlBQUFBREFBQUFBZ0FoWTI0OVpHbG5hV05sY25RZ2MyaGhNaUJ6WldOMWNtVWdjMlZ5ZG1W
  truststore.jks: L3UzKzdRQUFBQUlBQUFBREFBQUFBZ0FoWTI0OVpHbG5hV05sY25RZ2MyaGhNaUJ6WldOMWNtVWdjMlZ5ZG1W
  user_name: QURNSU4=

NOTE:

  1. Except for user_name rest of the data in the Secret are binary files.
  2. Due to a known issue in service catalog/OSB, the binary data in the Secret are encoded in base64 twice. While mounting the data from Secrets, Kubernetes decodes it once. Hence user will be required to decode the data one more time to get the actual binary file. We are trying to come up with a workaround for this.
  3. The client will require the DB ADMIN password and the wallet password(optional) also to connect/manage ADW. Users can pass these from the secret file created earlier(adw-secret.yaml). This is required as we don't want to store any credentials inside the broker.

Connecting to a provisioned ADW instance

Create a Kubernetes Secret with passwords

User need to create secret with DB Admin user password and wallet password. Edit the oci-service-broker/samples/adw/adw-demo-secret.yaml with proper base64 encoded value of the passwords. (Example: echo 's123456789S@' | base64).

Create the Secret.

kubectl create -f charts/oci-service-broker/samples/adw/adw-demo-secret.yaml

Injecting credentials and configurations

The file oci-service-broker/samples/adw/adw-demo.yaml contains a sample Kubernetes deployment yaml that shows how to:

  1. Read the credentials/configuration from the secret and decode it using initContainer.
  2. Inject admin password and wallet password from secret as environment variable into an application container.

Note: Please refer here for details on connecting to ADW from a java application. Download the Client Credentials step mentioned in the document is not required as it is already available in the secret created by the binding request.

apiVersion: extensions/v1beta1
kind: Deployment
metadata:
  name: adw-demo
spec:
  replicas: 1
  template:
    metadata:
      labels:
        app: adw-demo
    spec:
      # The credential files in the secret are base64 encoded twice and hence they need to be decoded for the programs to use them.
      # This decode-creds initContainer takes care of decoding the files and writing them to a shared volume from which db-app container
      # can read them and use it for connecting to ADW.
      initContainers:
      - name: decode-creds
        command:
        - bash
        - -c
        - "for i in `ls -1 /tmp/creds | grep -v user_name`; do cat /tmp/creds/$i  | base64 --decode > /creds/$i; done; ls -l /creds/*;"
        image: oraclelinux:7.4
        volumeMounts:
        - name: creds-raw
          mountPath: /tmp/creds
          readOnly: false
        - name: creds
          mountPath: /creds
      containers:
      # User application that uses credential files to connect to ADW.
      - name: db-app
        image: <USER_APPLICATION_IMAGE>
        env:
        # Pass DB ADMIN user name that is part of the secret created by the binding request.
        - name: DB_ADMIN_USER
          valueFrom:
            secretKeyRef:
              name: adw-demo-binding
              key: user_name
        # Pass DB ADMIN password. The password is managed by the user and hence not part of the secret created by the binding request.
        # In this example we read the password form secret adw-user-cred that is required to be created by the user.  
        - name: DB_ADMIN_PWD
          valueFrom:
            secretKeyRef:
              name: adw-user-cred
              key: password
        # Pass  Wallet password to enable application to read Oracle wallet. The password is managed by the user and hence not part of the secret created by the binding request.
        # In this example we read the password form secret adw-user-cred that is required to be created by the user.  
        - name: WALLET_PWD
          valueFrom:
            secretKeyRef:
              name: adw-user-cred
              key: walletPassword
        volumeMounts:
        - name: creds
          mountPath: /db-demo/creds
      volumes:
      # Volume for mouting the credentials file from Secret created by binding request.
      - name: creds-raw
        secret:
          secretName: adw-demo-binding
      # Shared Volume in which initContainer will save the decoded credential files and the db-app container reads.
      - name: creds
        emptyDir: {}

Important things to note:

  1. The volume creds-raw contains all credentials files from the Secret adw-demo-binding create by the bidning request.
  2. The initContainer decode-creds mounts the credentials file from 'creds-raw' and base64 decode them. The decoded files are written to volume creds.
  3. The container db-app mounts the decoded credentials from volume creds to directory /db-demo/creds.
  4. The DB ADMIN user name, password, wallet password are passed as environment variables (DB_ADMIN_USER, DB_ADMIN_PWD and WALLET_PWD).
  5. The DBADMIN password and the wallet password are read and passed from the secret (oci-service-broker/samples/adw/adw-demo-secret.yaml) we created earlier.

Deprovision

Delete Service Binding

Deleting the Service binding created in the previous step will result in the secret(that has the credentials) getting deleted. All Service Bindings for a ServiceInstance should be deleted before deleting the ServiceInstance.

kubectl delete -f charts/oci-service-broker/samples/adw/adw-binding-plain.yaml

Delete Service Instance

kubectl delete -f charts/oci-service-broker/samples/adw/adw-instance-plain.yaml
svcat get instances

Output:

NAME NAMESPACE CLASS PLAN STATUS
+----------------+-----------+-------------+----------+----------------+
adw-instance-1 catalog adw-service standard Deprovisioning

It usually takes 5-10 minutes for an instance to get deprovisioned. On successful deprviosining the ServiceInstance will be removed and won't be listed. In case of the existing instance actual instance won't be removed.

Use Secret to pass passwords

For the provisioning, resource requires the password contained in the secret file to be in JSON format

{ "password" : "s123456789S@"}

Kubernetes requires the secrets to be base64 encoded. One way to do this is to use base64 utility in Linux

echo '{ "password" : "s123456789S@"}' | base64

Create Secret:

Edit the values of 'password:' and 'walletPassword:' in oci-service-broker/samples/adw/adw-secret.yaml with appropriate base64 encoded strings

kubectl create -f charts/oci-service-broker/samples/adw/adw-secret.yaml

Yaml to provision ADW instance with password loaded from Kubernetes Secret (notice parametersFrom part)

cat charts/oci-service-broker/samples/adw/adw-instance.yaml

Yaml to provision ADW instance with password loaded from Kubernetes Secret (notice parametersFrom part)

cat charts/oci-service-broker/samples/adw/adw-binding.yaml