Skip to content

Latest commit

 

History

History
323 lines (238 loc) · 12.5 KB

quickstart-18c-xe.md

File metadata and controls

323 lines (238 loc) · 12.5 KB
Raw

El Carro Operator installation guide - Oracle 18c XE

El Carro is a new tool that allows users to keep full control of their database environment (root on a machine, sysdba in Oracle), while helping users automate several aspects of managing their database services.

El Carro helps you with the deployment and management of a database software (like Oracle database) on Kubernetes. You must have appropriate licensing rights to that database software to allow you to use it with El Carro (BYOL).

This quickstart aims to help get your licensed Oracle database up and running on Kubernetes. This guide is only intended for Oracle 18c XE which is free to use. If you prefer to use an Enterprise Edition of Oracle with El Carro and have a valid Oracle license, check out the quickstart guide for Oracle 12c EE or the quickstart guide for Oracle 19c EE.

Before you begin

The following variables will be used in this quickstart:

export DBNAME=<Must consist of only uppercase letters, and digits. For example: MYDB>
export PROJECT_ID=<your GCP project id>
export SERVICE_ACCOUNT_ID=<The ID for the service account to be used by El Carro>
export SERVICE_ACCOUNT=<fully qualified name of the compute service account to be used by El Carro (i.e. SERVICE_ACCOUNT_ID@PROJECT_ID.iam.gserviceaccount.com)>
export PATH_TO_EL_CARRO_RELEASE=<the complete path to the downloaded release directory>
export ZONE=<for example: us-central1-a>
export CLUSTER_NAME=<for example: cluster1>

Download El Carro software to your workstation as follows:

  1. Option 1: You can download it from El Carro GitHub repo. Choose one of the release versions, preferably the latest release. The release artifacts exist as release-artifacts.tar.gz.

  2. Option 2: You can choose one of the release versions, preferably the latest release, from this GCS bucket using gsutil.

gsutil -m cp -r gs://elcarro/latest $PATH_TO_EL_CARRO_RELEASE

Create a new GCP project or reuse an existing one to install El Carro. GCP provides free tier products. So if you are not already a GCP user, you can sign up for a free trial. :)

gcloud projects create $PROJECT_ID [--folder [...]]

Set gcloud config project to $PROJECT_ID

gcloud config set project $PROJECT_ID

Check gcloud config project

gcloud config get-value project

Create a new service account or reuse an existing one in your GCP project to install El Carro. Check out Creating and Managing Service Accounts if you need help creating or locating an existing service account.

To get El Carro up and running, you need to do one the following:

Express install

Run the express install script:

cd $PATH_TO_EL_CARRO_RELEASE/deploy
chmod +x ./install-18c-xe.sh

./install-18c-xe.sh --service_account $SERVICE_ACCOUNT

Optionally set CDB name, GKE cluster name, GKE zone

./install-18c-xe.sh --service_account $SERVICE_ACCOUNT --cdb_name $DBNAME --cluster_name $CLUSTER_NAME --gke_zone $ZONE

OR

Perform the manual install steps:

  • Check downloaded El Carro software
  • Create a containerized database image
  • Provision a kubernetes cluster. We recommend a cluster running Kubernetes/GKE version 1.17 or above.
  • Deploy the El Carro Operator to your Kubernetes cluster
  • Create an Instance (CDB) and Database (PDB) via the El Carro Operator

Check downloaded El Carro software

  • The operator.yaml is a collection of manifests that is used to deploy the El Carro Operator:
  • The ui.yaml is a collection of manifests that is used to deploy the El Carro UI.
  • The dbimage directory contains a set of files for building a containerized database image described in the next section.
  • The samples directory contains the manifests for creating Custom Resources (CRs) mentioned in this user guide.
  • The workflows directory is similar to samples, but the manifests there are the DRY templates that can be hydrated with kpt to create/manage the same Custom Resources (CRs).

We recommend starting with the samples first, but as you become more familiar with El Carro, consider the more advanced use of declarative workflows that can be achieved with the parameterized templates in the workflows directory.

The db_monitor.yaml and setup_monitoring.sh files are useful to deploy the El Carro monitoring and viewing metrics.

Creating a containerized Oracle database image

There are two options to build the actual container database image: Using Google Cloud Build or locally using Docker.

Using Google Cloud Build to create a containerized Oracle database image (Recommended)

  1. Create a new GCP project or reuse an existing one with the following settings:

    gcloud projects create $PROJECT_ID [--folder [...]]
gcloud services enable container.googleapis.com anthos.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com --project $PROJECT_ID

    Though the default compute service account can be used with El Carro, we recommend creating a dedicated one as follows:

    gcloud iam service-accounts create $SERVICE_ACCOUNT_ID --project $PROJECT_ID
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
gcloud projects add-iam-policy-binding $PROJECT_ID --member=serviceAccount:service-${PROJECT_NUMBER}@containerregistry.iam.gserviceaccount.com --role=roles/containerregistry.ServiceAgent

  2. Trigger the Google Cloud Build pipeline

    When using Oracle 18c XE, you can only create seeded (containing a CDB) images. To create a seeded image, run the following:

    cd $PATH_TO_EL_CARRO_RELEASE/dbimage
chmod +x ./image_build.sh

./image_build.sh --db_version=18c --create_cdb=true --cdb_name=$DBNAME --no_dry_run --project_id=$PROJECT_ID

Executing the following command:
[...]

  3. Verify that your containerized database image was successfully created.

    Cloud Build should take around 45 minutes to build the image. To verify the image that was created, run:

    gcloud container images list --project $PROJECT_ID --repository gcr.io/$PROJECT_ID/oracle-database-images

NAME
gcr.io/$PROJECT_ID/oracle-database-images/oracle-18c-xe-seeded-$DBNAME

gcloud container images describe gcr.io/$PROJECT_ID/oracle-database-images/oracle-18c-xe-seeded-$DBNAME

image_summary:
  digest: sha256:ce9b44ccab513101f51516aafea782dc86749a08d02a20232f78156fd4f8a52c
  fully_qualified_digest: gcr.io/$PROJECT_ID/oracle-database-images/oracle-18c-seeded-$DBNAME@sha256:ce9b44ccab513101f51516aafea782dc86749a08d02a20232f78156fd4f8a52c
  registry: gcr.io
  repository: $PROJECT_ID/oracle-database-images/oracle-18c-xe-seeded-$DBNAME

Building a containerized Oracle database image locally using Docker

If you're not able or prefer not to use Google cloud build to create a containerized database image, you can build an image locally using Docker. You need to push your locally built image to a registry that your Kubernetes cluster can pull images from. You must have Docker installed before proceeding with a local containerized database image build.

Note that in the current release, local build only works with Linux systems. Additional support for other operating systems like Windows, Mac OS, etc. will be added in future releases.

  1. Trigger the image creation script

    When using Oracle 18c XE, you can only create seeded (containing a CDB) images. To create a seeded image, run the following:

    cd $PATH_TO_EL_CARRO_RELEASE/dbimage
chmod +x ./image_build.sh

./image_build.sh --local_build=true --db_version=18c --create_cdb=true --cdb_name=$DBNAME --no_dry_run --project_id=local-build

  2. Verify that your containerized database image was successfully created.

    Docker should take around 20-30 minutes to build the image. To verify that your image was successfully created, run the following command:

    docker images
REPOSITORY                                                                               TAG       IMAGE ID       CREATED       SIZE
gcr.io/local-build/oracle-database-images/oracle-18c-xe-seeded-$DBNAME         latest    c766d980c9a0   2 hours ago   11.8GB

  3. Re-tag your locally built image if necessary using the docker tag command and push it to a registry that your Kubernetes cluster can pull images from using the docker push command.

Provisioning a Kubernetes cluster on GKE to run El Carro

To provision a Kubernetes cluster on Google Kubernetes Engine (GKE), run the following command:

gcloud container clusters create $CLUSTER_NAME --release-channel rapid --machine-type=n1-standard-4 --num-nodes 2 --zone $ZONE --project $PROJECT_ID --scopes gke-default,compute-rw,cloud-platform,https://www.googleapis.com/auth/dataaccessauditlogging --service-account $SERVICE_ACCOUNT

To get the cluster ready for El Carro, create a VolumeSnapshotClass as follows:

kubectl create -f $PATH_TO_EL_CARRO_RELEASE/deploy/csi/gce_pd_volume_snapshot_class.yaml

Verify that your VolumeSnapshotClass was properly created by running:

kubectl get volumesnapshotclass
NAME                        AGE
csi-gce-pd-snapshot-class   78s

Deploying the El Carro Operator to a Kubernetes cluster

You can use kubectl to deploy the El Carro Operator to your cluster by running:

kubectl apply -f $PATH_TO_EL_CARRO_RELEASE/operator.yaml
namespace/operator-system created
[...]

Creating an El Carro Instance

An instance consists of Oracle software running in a container and a CDB. To create an instance:

  • Create a namespace to host your instance by running:

    kubectl create namespace db

  • Modify $PATH_TO_EL_CARRO_RELEASE/samples/v1alpha1_instance_18c_XE.yaml to include the link to the database service image you built earlier.

  • Apply the modified yaml file by running:

    kubectl apply -f $PATH_TO_EL_CARRO_RELEASE/samples/v1alpha1_instance_18c_XE.yaml -n db

Monitor creation of your instance by running:

kubectl get -w instances.oracle.db.anthosapis.com -n db
NAME   DB ENGINE   VERSION   EDITION      ENDPOINT      URL                DB NAMES   BACKUP ID   READYSTATUS   READYREASON        DBREADYSTATUS   DBREADYREASON
mydb   Oracle      18c       Express      mydb-svc.db   34.71.69.25:6021                          False         CreateInProgress

Once your instance is ready, the READYSTATUS and DBREADYSTATUS will both flip to TRUE.

Tip: You can monitor the logs from the El Carro operator by running:

kubectl logs -l control-plane=controller-manager -n operator-system -c manager -f

Creating a PDB (Database)

To store and query data, create a PDB and attach it to the instance you created in the previous step by running:

kubectl apply -f $PATH_TO_EL_CARRO_RELEASE/samples/v1alpha1_database_pdb1.yaml -n db

Monitor creation of your PDB by running:

kubectl get -w databases.oracle.db.anthosapis.com -n db
NAME   INSTANCE   USERS                                 PHASE   DATABASEREADYSTATUS   DATABASEREADYREASON   USERREADYSTATUS   USERREADYREASON
pdb1   mydb       ["superuser","scott","proberuser"]    Ready   True                  CreateComplete        True              SyncComplete

Once your PDB is ready, the DATABASEREADYSTATUS and USERREADYSTATUS will both flip to TRUE.

You can access your PDB externally by using sqlplus:

sqlplus scott/tiger@$INSTANCE_URL/pdb1.gke

Replace $INSTANCE_URL with the URL that was assigned to your instance.

ORACLE 18c XE Limitations

Oracle 18c XE has the following resource limitations:

  • Up to 12 GB of user data
  • Up to 2 GB of database RAM
  • Up to 2 CPU threads
  • Up to 3 Pluggable Databases

More details on what's included in Oracle 18c XE can be found on Oracle's website.