I’m excited to introduce the Oracle Cloud Infrastructure (OCI) Modules for PowerShell. The OCI Modules for PowerShell are now publicly available on GitHub and PowerShell Gallery. These modules enable PowerShell users to manage OCI services using PowerShell Cmdlets. They support all the same services, service features, and regions that are supported in Oracle Cloud ’s other public SDKs and OCI CLI.
OCI Modules for PowerShell are publicly released on a weekly basis supporting any new available services and regions launched within Oracle cloud.
Create and set up your Oracle Cloud Infrastructure Account.
Complete the basic configuration required for the SDK.
These links point to the extensive Oracle Cloud documentation. For quick step-by-step instructions on creating Oracle Cloud Account and related config to use developer tools, I recommend following the first two sections of this blog that I wrote previously.
PowerShell Core version 6.0 or higher
First, let’s talk about PowerShell before we jump into understanding and using OCI PowerShell modules. The reason behind my team launching this product becomes much clearer once I describe PowerShell and its uniqueness.
PowerShell is a command line shell. It has its own scripting language and is a cross-platform task automation and configuration management framework.
In this blog, I felt it important to do a brief comparison of PowerShell and Bash shell. Most developers are familiar with Bash or a similar shell available by default in Linux and MacOS.
PowerShell and Bash share the following characteristics:
Command line shell
Built in command-set is easily extendable
Cross-platform, available for MacOS, Linux, and Windows
Profile feature in PowerShell is similar to .bashrc
Has a powerful scripting language and environment
Tab completion for commands and parameters
Below are some of the differences between the two shells:
Commands are popularly known as cmdlets.
|Commands are called commands.|
|Input and output are object-based.||
Input and output are text-based.
Support for aliases limited to commands or functions
Support for aliases (using cmd line or .bashrc) for any string.
Configuration Management tool primarily on Windows because of its better integration with Windows (Exchange, Registry, Management).
|Suited for development environment on Linux type systems|
The previous table by no means covers all aspects of these shells, but it gives a high-level view. I want to highlight and discuss one of the primary differences: input and output for PowerShell is object-based, compared to text-based for bash and similar shells. PowerShell is built on the .NET common language runtime (CLR) and accepts and returns .NET objects. This fundamental change brings entirely new tools and methods for automation.
Here’s an example showcasing this difference and how powerful this difference makes PowerShell and OCI PowerShell Modules. Let’s say we have a task of getting all region code values of OCI Region. The following screenshots show the simplest solution in bash using OCI CLI and in PowerShell using OCI PowerShell Modules.
The first screenshot shows OCI CLI used on Bash. In Bash, working on the output data of a CLI command requires us to use JMESPath language (query language to work with json) or a complex combination of regular expressions with sed, awk, and grep utilities.
In PowerShell, as you can see on the second image, because the cmdlets return .NET objects, we can access any field using a dot operator. It’s closer to writing programmatic code in object-oriented language.
A PowerShell module is a package that contains PowerShell commands, such as cmdlets, providers, functions, workflows, variables, and aliases. PowerShell users can write commands by using modules to organize their commands and share them with others. Installing a module can add the commands in the modules to your PowerShell session, and you can use them like the built-in commands.
Oracle Cloud Infrastructure Modules for PowerShell are modules for OCI services. Each OCI service gets one PowerShell Module, allowing you the flexibility to install only the module for the service you require to use. You can also install all modules together.
OCI PowerShell modules enable PowerShell you to manage OCI services using PowerShell Cmdlets (Commands). This interface, native to .NET, is faster, efficient, and familiar for Oracle Cloud .NET users.
Now, I highlight some features related to usage of OCI Modules for PowerShell. The following screenshots have Oracle Cloud resource identifiers (OCIDs) redacted for security purposes.
Once you have PowerShell installed on your machine, using OCI Modules for PowerShell is easy and quick. It comes preinstalled on Windows OS. If you’ve bootstrapped Oracle Cloud before or followed the prerequisites mentioned in my previous blog, executing your first OCI cmdlet requires only two commands. I use Identity service in this example, but you can use any OCI service you ’re interested in.
Install-Module -Name "OCI.PSModules.Identity" -Repository PSGallery Get-OCIIdentityRegionsList
The repository “PSGallery” points to PowerShell Gallery, maintained by Microsoft, and is set in PowerShell by default. Because PowerShell already comes with .NET runtime, you don’t need to install extra dependencies. OCI PowerShell modules are native to PowerShell, which allows faster command execution speed.
You can find all OCI modules available in PowerShell Gallery using the following command:
Find-Module -Name OCI.PSModules.* -Repository PSGallery
Install all OCI Modules by piping the previous command with Install-Module, as shown:
Find-Module -Name OCI.PSModules.* -Repository PSGallery | Install-Module
You can find all the commands within a module, such as the OCI Identity service module, using the following prompt:
Get-Command -Module OCI.PSModules.Identity
You can set some config values—such as region, profile from config file, and the path to the config file—throughout a PowerShell session for cmdlets to use them, as shown in the following screenshot:
Typically, I use the default path for config file (~/.oci/config) and set my region in the config file itself. I primarily use session preferences to set my profile value from config file.
One interesting feature in OCI cmdlets that differs from other OCI developer tools is the ability to look back at the history of commands that we executed in our PowerShell session. We can access input and output of each command using the history store, which is stored in an environment variable, $OCICmdletHistory. This feature enables you to access past response object member values in current commands. The following screenshot explores the OCICmdletHistory environment variable and its members in brief.
You can use in cmdlets to return a collection of objects. Invoke it using the Page and Limit parameters. To get all the objects in a list operation, OCI cmdlets also support the All parameter. The following screenshot shows an example of how to get supported the OS image list for instances in Oracle Cloud Infrastructure Compute service. It clarifies how to use pagination parameters. We also use the cmdlet history variable in the following example to access the ‘next page (OpcNextPage)’ parameter returned in the previous response.
You can wait on resources to reach a particular lifecycle state using the PowerShell cmdlets WaitForLifecycleState parameter. The waiters feature is applicable only to OCI operations that return a resource associated with different lifecycle states. The following example creates a virtual cloud network (VCN) in Oracle Cloud Networking service and then waits for it to become available. The waiter parameters used in the example are WaitForLifecycleState, WaitIntervalSeconds, and MaxWaitAttempts. All parameters are optional and can be used individually with an OCI cmdlet.
I want to leave you with an example of what you can achieve with an example of data piping, done using the PowerShell pipelining feature. This one-line command retrieves all the Compute instances across all compartments in an OCI region, including the VNIC and image details associated with the instances, using only the tenancy OCID as input. People who use Oracle Cloud know that VNIC attachment is the link between a VNIC and an instance. Therefore, it serves as a good starting point.
Pipelining with SDKs or CLI requires a decent amount of code. Using PowerShell pipelines, you can do it in one line. For a new PowerShell user, the following pipeline might seem intimidating, but for a regular user, it’s a simple one-liner that you can use to get quick useful data.
As a learning exercise, I encourage you to try the pipeline part by part to understand how it gets to the solution.
In this post, we were introduced to another powerful tool that helps manage resources on Oracle Cloud. We learned how easy and quick it is to install and start using these modules. Because PowerShell is available cross platform across MacOS, Linux and Windows, anyone can use it as their preferred shell. I urge you to try it and see for yourself how a faster command execution time, along with powerful data pipelining features, generate quick, useful data on Oracle Cloud.
To get more familiar with Oracle Cloud Infrastructure Modules for PowerShell, refer the following resources: