Part #2: Securely Dockerising the Oracle PaaS Service Manager (PSM CLI)

TL;DR: Using the rubiconxred/psm docker image with external secrets, we can securely interact with psm CLI without needing anything else installed on our machine. No python, no pip dependency downloads, no secrets stored in the image; the only dependency is docker.

This is Part #2 in our 3 Part series on Oracle PaaS Service Manager (PSM). In the first post we showed you how to locate and download the PSM CLI.

We can use the dockerised image in exactly the same way as we would use the native psm cli while avoiding all of the upfront pain (e.g. conflicts between the python dependencies of other CLIs).

A co-worker shared their frustration from earlier experiences, after I shared this approach on our internal collaboration portal.

I wish I had done the docker-first approach for the CLI tools, as I have been through hell with the CLIs for aws, psm and opc etc and their shared use of python!!

If this resonates with you, well then now is the time to switch to running dockerised CLI tools. If you're just getting started with psm then save yourself the pain. Unless you are not using python for anything else, you're probably gonna have a bad time. Do you want to have a bad time?

Beware of Imitations

I wrote this article because the other articles I had seen were giving really bad advice such as instructing readers to bake their secrets into the docker image itself. This is not a good idea as all it would take is for someone to do a docker push to a public registry and now the world has full access to your entire Oracle Cloud domain. Don't be a sucker!

Only prerequisite. docker.

You shouldn't need anything other than docker to run through this guide. If you don't have it installed head over to the Docker Installation Guide or if you're on Linux/Mac, you can simply install with the following:

curl -fsSL get.docker.com -o get-docker.sh  
sh get-docker.sh  

Creating our psm wrapper

Establishing a dockerised setup for psm can be done by simply adding a docker wrapper to your PATH. Cool hey?!

Let's create a psm file on the PATH so it behaves exactly like the natively installed psm. We will take the contents below and put it in /usr/local/bin/psm (although it could be anywhere so long as it's on the PATH.

run_psm(){  
  docker run -ti \
    -e PSM_IDENTITY_DOMAIN=idcs-XXXXXXXXXXXXXXXXXXXXXXXXXXXX \
    -e PSM_USERNAME=user@company.com \
    -e PSM_PASSWORD=password-goes-here \
    -e PSM_REGION=us \
    -w /data -v $PWD:/data --rm \
    rubiconxred/psm psm "$@"
}
run_psm "$@"  

Finally, update the placeholders with the real values you want for PSM_IDENTITY_DOMAIN, PSM_USERNAME, PSM_PASSWORD and PSM_REGION. If you don't know how to find these, I'd recommend checking out Andrew Dorman's Getting Started with PSM guide. The identity domain in particular can be notoriously difficult to find.

Now, you're done. You can interact with psm as per normal.

psm help  

Hold up, PSM what?

I know, I know, I couldn't help but jump to the solution. It's bad I know. So let's wind it all back... What is psm and why should I care?

The Oracle PaaS Service Manager Command-Line Interface (psm) is a useful tool for managing the lifecycle of various services in the Oracle Public Cloud. It's a thin wrapper over the various PaaS REST APIs to make it easier to perform cloud lifecycle automation from scripts.

So what can I do with it?

Well... Plenty of things! An execution of psm help will show that we can manage and automate the lifecycle of the following services (as at July 2018; I'm sure there is more to come).

AVAILABLE SERVICES  
  o ADBC
       Oracle Autonomous Database Cloud
  o AIACS
       Oracle Adaptive Intelligent Cloud Service AIACS
  o AIPOD
       Oracle Adaptive Intelligent Cloud Service POD
  o ANALYTICS
       Oracle Analytics Cloud
  o APICS
       Oracle API Platform Cloud Service
  o APICatalog
       Oracle API Catalog Service
  o BDCSCE
       Oracle Big Data Cloud
  o BOTSCFG
       Oracle Bots Configuration Service
  o BOTSCON
       Oracle Bots Connector Service
  o BOTSINT
       Oracle Bots Intent Service
  o BOTSMGM
       Oracle Bots Management API Service
  o BOTSPIP
       Oracle Bots Pipeline Service
  o CEC
       Oracle Content and Experience Cloud Suite
  o CECS
       Oracle Content and Experience Cloud
  o CONTAINER
       Oracle Container Cloud Service
  o CXAANA
       Oracle CxA Analytics Service 
  o CXACFG
       Oracle CxA Configuration Service 
  o CXACOL
       Oracle CxA Collector Service 
  o CXAPOD
       Oracle CxA Pod Cloud Service 
  o ContainerRegistry
       Oracle Container Registry Service
  o DHCS
       Oracle Data Hub Cloud Service
  o IOTAssetMon
       Oracle IoT Asset Monitoring Cloud Service
  o IOTConnectedWrker
       Oracle IoT Connected Worker Cloud Service
  o IOTEnterpriseApps
       Oracle Internet of Things Cloud - Enterprise
  o IOTFleetMon
       Oracle IoT Fleet Monitoring Cloud Service
  o IOTProdMonitoring
       Oracle IoT Production Monitoring Cloud Service
  o IOTSvcAsset
       Oracle IoT Asset Monitoring CX Cloud Service
  o IntegrationCloud
       Oracle Integration Cloud
  o jcs
       Oracle Java Cloud Service
  o MobileCCC
       Oracle Mobile Custom Code Container
  o MobileCorePOD
       Oracle Mobile Core POD
  o MySQLCS
       Oracle MySQL Cloud Service
  o OEHCS
       Oracle Event Hub Cloud Service
  o OEHPCS
       Oracle Event Hub Cloud Service - Dedicated
  o OMCE
       Oracle Mobile Cloud Metering Service
  o OMCEXTERNAL
       Oracle Management Cloud Service
  o OMCP
       Oracle Management Cloud Platform Service
  o SOA
       Oracle SOA Cloud Service
  o SSI
       Oracle Self-Service Integration Cloud Service
  o SSIP
       Oracle Self-Service Integration Platform
  o VisualBuilder
       Oracle Visual Builder
  o accs
       Oracle Application Container Cloud Service
  o caching
       Oracle Application Cache
  o containerPod
       Oracle Container Cluster Service
  o dbcs
       Oracle Database Cloud Service
  o dics
       Oracle Data Integration Platform Cloud Service
  o ggcs
       Oracle GoldenGate Cloud Service
  o stack
       Oracle Cloud Stack Manager
  o setup
       Configure psm client options
  o cleanup
       Remove configured psm client options
  o update
       Update psm client to latest version
  o log
       View or update psm client log level
  o help
       Show help

How did you create your image?

Ok, so if you have read this far, good work. You might be wondering how you can create a secure docker image under your own namespace rather than relying on the one I have pre-built. I've uploaded the Dockerfile I used to Github for your convenience. To build your own image, simply clone the repository, download psmcli.zip locally using one of the approaches in the earlier post, place it in the same directory as the Dockerfile and execute a docker build.

git clone https://github.com/rubiconred/psmcli  
cd psmcli  
curl -X GET -u ${PSM_USERNAME}:${PSM_PASSWORD} \  
     -H X-ID-TENANT-NAME:${PSM_IDENTITY_DOMAIN} \ 
https://psm.${PSM_REGION}.oraclecloud.com/paas/core/api/v1.1/cli/${PSM_IDENTITY_DOMAIN}/client -o psmcli.zip  
docker build -t psm-cli .  

Now to use your image simply replace your wrapper script to have psm-cli instead of rubiconxred/psm. That's it!

Distributing your image for easy access anywhere

One of the nice things about the image is that it doesn't contain any secrets and so is safe to push to a Docker Registry. Once pushed to a registry, you or anyone (or at least anyone authorised in case of a private registry) can pull down the image anywhere that it is needed.

Of course, you can skip this step altogether by using the pre-built rubiconxred/psm from Docker Hub.

If you do indeed want to use your own image repository on a docker registry, all that is needed is an active Docker Hub account. If you don't have one you can sign up for free at https://hub.docker.com/

Step 1: Make sure you have performed a docker login first.

Step 2: If you are using the image tagged as psm-cli. Be sure to first tag to with your namespace from Docker Hub.

docker tag psm-cli yournamespace/psm  

Step 3: Push your image

docker push yournamespace/psm  

Thanks!

I hope you found this useful. If you did, please share this post or leave a comment below.

Craig Barr

I am a Software Engineer with a decade of experience empowering Enterprises in Banking, Logistics, Manufacturing with Service-Oriented Architecture, Microservices and Cloud Computing.

Brisbane, Australia https://twitter.com/craigbarrau