Categories
Oracle Cloud Infrastructure

Administering OCI from WSL

Who is this article for:

This is written for those of us who use Windows as their primary workstation but also like to have Linux readily available to them. I describe a minimal setup I recommend for OCI administration purposes.

Introduction

While it’s almost always possible to develop or administer cloud infrastructure from Windows using its native command line or Powershell, most examples you’ll find out there on internet will be written with Linux or MacOS in mind. Especially when we’re talking about open source software! There are situations when you’ll be better served, spend less time tinkering or have better support if you’re able to use Linux.
The fact is, knowing Linux today is pretty much an unavoidable necessity for a Cloud Architect, even if you were using Windows exclusively before and today are working with nothing but Azure!

As a Windows user, in the past you had to jump through few hoops to get access to Linux shell.

Before Windows 10, the options for running Linux locally on a Windows machine were the following:

  • Dual-boot between Windows and Linux (gah!)
  • Run Cygwin (collection of POSIX-compatible tools that offer a Linux-like environment).
  • Run Git Bash that includes a collection of Linux tools compiled to work on Windows. As most of us have Git for Windows installed anyway, the Git Bash will be already there in most cases.
  • Run a full Linux VM in Virtualbox, VMWare Workstation player or Hyper-V

All of them have their merits and are more or less compatible, easy to use or resource-heavy.
Since Windows 10, Microsoft introduced another more “native” way, the WSL: https://en.wikipedia.org/wiki/Windows_Subsystem_for_Linux

There a several Linux distributions that are available to install to WSL from Microsoft Store – Debian, Ubuntu, Suse etc.

Once WSL2 is officially released, it will even run a proper Linux kernel (the WSL1 only has a compatibility layer translating linux syscalls to Windows API calls). This article describes the WSL – I’ll post an update when I’ll be able to install the WSL2.

Installing WSL and Linux distribution

First, let’s rapidly install WSL and one of the Linux distributions available on Microsoft Store: please follow this documentation to do that https://docs.microsoft.com/en-us/windows/wsl/install-win10

In my case, I already have Ubuntu installed and will install an additional one (you can have multiple distributions installed). This time I’ll be selecting Debian. Today (Janyary 2020) this will install Debian 10 “Buster”.

Launching WSL

Just search for “Debian” (or whatever distribution you’ve just installed) in the Windows start menu and launch the application

The very first launch will take some time, after that you’ll be asked to set up the user and its password. All the subsequent launches will be much shorter. At the end you’ll be presented with a standard linux bash prompt and positioned in your linux home directory (which is different from your windows home directory!)

Treat is like a regular linux – many of the linux utilities will run as usual, you can install new packages using apt and so forth. Some things won’t run on current WSL but will once WSL2 is available, for example Docker. WSL is also in some ways slower than native Linux, this will be corrected in WSL2 too.

Verifying installation

First, let’s verify that WSL can connect to the internet, you’ll need it to access and administer your cloud resources.

A remark: unlike Ubuntu, my Debian installation on WSL is missing a “SUID” bit on the ping binary for some reason, without which it’s only working when invoked by root. To rectify this I ran

sudo chmod u+s /bin/ping

Ping something on internet: if it works, then your connection is good. If it doesn’t, you may be working behind a proxy (often the case in corporate environments). I’m preparing another post covering this situation, stay tuned to the blog!

ping -c 4 8.8.8.8

Update your Debian packages to the latest versions

sudo apt update && sudo apt upgrade -y

Once done, you’ll end up with all the available updates installed

From WSL, you’ll be able to call the windows executable files and even combine DOS, Windows and Linux commands in the same command line:

Ok, maybe this example isn’t very useful, but it’s fun and is showing what can be done 🙂

Installing OCI CLI

OCI CLI (“Command Line Interface”) is a standalone utility that gives you another way to administer the OCI resources. It implements public APIs, the same APIs that are used but OCI console and development SDKs. Having CLI installed is required in some cases (for example for OKE administration), but it has many more uses.

  • The command for OCI CLI is “oci

I’ll show you how to install OCI CLI and authenticate it (let it access the APIs). If you want to know more than my short notes, here’s the documentation: https://docs.cloud.oracle.com/iaas/Content/API/Concepts/cliconcepts.htm

  • The CLI itself is written in Python and you’ll need to install Python 3 first (Python 3.5 or newer). I’ll also install distutils, curl and wget utilities at the same time, they will be used later:
sudo apt install python3 python3-distutils curl wget -y

This will install a minimal installation of python 3.7 (as of January 2020, on Debian Buster)

  • Verify the python installation is working:
python3 -c "print('hello world')"
  • Install it

I’ll install the CLI using the “Quick Start” installation script from https://docs.cloud.oracle.com/iaas/Content/API/SDKDocs/cliinstall.htm

bash -c "$(curl -L https://raw.githubusercontent.com/oracle/oci-cli/master/scripts/install/install.sh)"

The installer script will ask you to provide paths for config files and python modules- you can keep all the default values (just press Enter after the prompts). The installer then will download and install all the required python packages.

After the installation completion, the very first run of the CLI will be a little slow – python will spend some time precompiling the modules, but all the subsequent runs will be much faster.

oci --version

Connecting CLI to your tenancy

You need to authenticate the CLI – point it to your tenancy and give it appropriate rights.

  • First, let’s create a special user that will be used to access the APIs. While you can use your own user, the best practice is to use a separate one as a “service account” dedicated for this purpose.

In OCI console, go to Main Menu > Identity > Users and press “Create User” button. I’ll name mine “cli.user

Then I’ll go to the created user and press “Edit User Capabilities” button

I’ll keep selected only the “API KEYS” capability – this user couldn’t be used for anything else. Always remove capabilities you don’t need, your security people will love you 😉

Right now, the “cli.user” user has no rights whatsoever – it was just created but not assigned to any group. The group assignment will determine the effective rights. More reading on the group management on OCI: https://docs.cloud.oracle.com/iaas/Content/Identity/Tasks/managinggroups.htm

I’ll add this user to “Workshops” group that I already have. If you didn’t set up any groups or policies yet, you may use the default group “Administrators”, although this may open to much rights to the cli.user. More about security policies: https://docs.cloud.oracle.com/iaas/Content/Identity/Concepts/policies.htm

Next, I go back to the WSL command line and using the OCI CLI, I’ll create the API keys that will be associated with the cli.user.

oci setup config

This command will ask you several questions. To answer these, you’ll need to collect some info

  • You can accept the default value for config file placement (press “Enter“)
  • User OCID: copy it from user’s page
  • Tenancy OCID: copy it from Main Menu > Administration > Tenancy Details
  • Region: enter the region you’re working with
  • Answer “y” to the question “Do you want to generate a new RSA key pair?”
  • You can accept default values for key location and name if you wish
  • Show the contents of the generated public key and copy it to the clipboard (select everything including the lines with “—” characters)
cd ~/.oci
cat oci_api_key_public.pem 
  • Go back to the console, open cli.user and click “Add Public Key” button, paste the key’s contents and click “Add” button:
  • If everything went well, you’ll see a “fingerprint” value shown in the console:

You can double check: this should be the same value as found in ~/.oci/config file

Verifying CLI installation

Run oci os ns get command – it should return the tenancy’s object storage namespace

Let’s try to list the availability domains in the current region: this command will return all the ADs in JSON format:

oci iam availability-domain list

What else can you do with OCI CLI?

Pretty much anything. Anything you can do in the OCI portal will also be doable using CLI, and even more. You can find the list of supported OCI services here: https://docs.cloud.oracle.com/iaas/Content/API/Concepts/cliconcepts.htm

The command reference can be found here (2.8.1 is the last GA version available today, January 2020) : https://docs.cloud.oracle.com/iaas/tools/oci-cli/2.8.1/oci_cli_docs/

Maybe one of the most frequent uses is to stop and start instances. Let’s try this!

oci compute instance action --instance-id ocid1.instance.oc1.eu-frankfurt-1.antheljtfa2l3sychohvawom5kooyi53glohvn75et3tylus2w6zul6wtcmq --action START --wait-for-state RUNNING

If the instance was stopped before, it will be started and the command will return once the instance transitioned to “RUNNING” state.

If the “–wait-for-state RUNNING” flag isn’t used, the command will return immediately.

Other tools to install into WSL

What else can be useful in this Linux environment? This is really up to you!

I often work on infrastructure automation (people like to call it “Infrastructure as Code”), so I tend always have the following installed:

I also tend to have additional languages installed – java, node.js, go, c# and also other things. This is easy on Linux, there are tons of open source packages to choose from.

This is all for now,

Keep hacking (•̀ᴗ•́)و ̑̑

3 replies on “Administering OCI from WSL”

Leave a Reply