Skip to content
Permalink
Fetching contributors…
Cannot retrieve contributors at this time
387 lines (292 sloc) 17.2 KB

Autonomous Transaction Processing Service

Introduction

Autonomous Transaction Processing(ATP) is a managed OCI Database service built on top of the Oracle Autonomous Database. ATP service is also offered via OCI Service Broker thereby making it easy for applications to provision and integrate seamlessly with ATP.

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

Sample Policy:

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

Service Provision Request Parameters

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

Parameter Description Type Mandatory
name The display name for the ATP instance. string yes
dbName Database Name. string yes
compartmentId The OCI compartment where the ATP 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 ATP Service will pre-provision a DB Admin user when it provisions an ATP instance. The user needs to provide a password to be set for this Admin user.
The OCI ATP 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 ATP instance. object no
definedTags The defined tags that are to be used for tagging the ATP instance. object no

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 ATP. 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 ATP. 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 ATP are available under oci-service-broker/samples/atp directory.

Provisioning

A sample Kubernetes resource yaml to provision an ATP instance.

cat oci-service-broker/samples/atp/atp-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 an ATP ServiceInstance

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

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

Get instance status

svcat get instances

Output:

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

It usually takes 10-15 minutes for the provisioning to complete. Once the ATP 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-atp-demo-1 catalog atp-service standard Ready

Binding

Once the ATP Instance is provisioned the applications will require credentials/configuration to connect to the provisioned ATP 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 oci-service-broker/samples/atp/atp-binding-plain.yaml

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

Creating an ATP ServiceBinding resource

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

Get Binding status

svcat get bindings

Output:

NAME NAMESPACE INSTANCE STATUS
+-------------+-----------+----------------+--------+
atp-demo-binding   catalog     osb-atp-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 atp-demo-binding -o yaml

Output:

apiVersion: v1
kind: Secret
type: Opaque
metadata:
  creationTimestamp: 2018-09-20T19:54:02Z
  name: atp-demo-binding
  namespace: catalog
  resourceVersion: "116279449"
  selfLink: /api/v1/namespaces/catalog/secrets/atp-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 ATP. Users can pass these from the secret file created earlier(atp-secret.yaml). This is required as we don't want to store any credentials inside the broker.

Connecting to a provisioned ATP 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/atp/atp-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/atp/atp-demo-secret.yaml

Injecting credentials and configurations

The file oci-service-broker/samples/atp/atp-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 ATP 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: atp-demo
spec:
  replicas: 1
  template:
    metadata:
      labels:
        app: atp-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 ATP.
      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 ATP.
      - 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: atp-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 atp-user-cred that is required to be created by the user.  
        - name: DB_ADMIN_PWD
          valueFrom:
            secretKeyRef:
              name: atp-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 atp-user-cred that is required to be created by the user.  
        - name: WALLET_PWD
          valueFrom:
            secretKeyRef:
              name: atp-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: atp-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 atp-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/atp/atp-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/atp/atp-binding-plain.yaml

Delete Service Instance

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

Output:

NAME NAMESPACE CLASS PLAN STATUS
+----------------+-----------+-------------+----------+----------------+
atp-instance-1 catalog atp-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.

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/atp/atp-secret.yaml with appropriate base64 encoded strings.

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

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

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

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

cat charts/oci-service-broker/samples/atp/atp-binding.yaml
You can’t perform that action at this time.