Getting Started
This topic describes how to install and configure the OCI Modules for PowerShell.
This topic describes how to install and configure the OCI Modules for PowerShell.
Prerequisites
Be sure to satisfy all the requirements listed here.
Installing Modules
- Start a PowerShell session:
- On Windows, launch PowerShell from the Start Menu.
-
On Linux or MacOS, run
pwsh
from a shell prompt:$ pwsh PowerShell 7.1.0 Copyright (c) Microsoft Corporation. All rights reserved. https://aka.ms/powershell Type 'help' to get help. PS /Users/username>
-
To install all OCI modules, install the base module:
Install-Module OCI.PSModules
Note
Uninstalling theOCI.PSModules
module will not uninstall other OCI modules. To uninstall a specific OCI module installed by this module, theOCI.PSModules
module will have to be uninstalled first. - You can install just the modules for an individual service. Cmdlets
corresponding to each OCI service supported by OCI
Modules for PowerShell are packaged into an individual Powershell module
named
OCI.PSModules.<ServiceName>
. - Continue to either Installing from PowerShell Gallery or Installing from GitHub.
Installing from PowerShell Gallery
-
By default, PowerShell Gallery ("PS Gallery") is configured as a PSRepository. This can be verified by running the
Get-PSRepository
command:PS /> Get-PSRepository Name InstallationPolicy SourceLocation ---- ------------------ -------------- PSGallery Untrusted https://www.powershellgallery.com/api/v2
-
You can set PS Gallery as a trusted repository to avoid prompts every time you attempt to install a module from PS Gallery:
PS /> Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
-
PowerShell modules that correspond to a supported OCI service are called service modules. To install a service module run the Install-Module command. This example installs the service module for the OCI Identity service:
PS /> Install-Module -Name OCI.PSModules.Identity
Note
Each service module depends on theOCI.PSModules.Common
(Common Module), which offers functionality common to all service modules. Installing a service module will also install the corresponding version ofOCI.PSModules.Common
for that service module. - Installed modules can be found in the path specified by the
$Env:PSModulePath
environment variable, or by running the Get-Module command with theListAvailable
parameter.PS /> Get-Module -ListAvailable
Installing from GitHub
To install the OCI PowerShell modules from GitHub:
- Download the latest OCI Modules artifacts and extract them into a local
directory.Note
Cmdlets corresponding to each OCI service supported by OCI Modules for PowerShell are packaged into an individual Powershell module namedOCI.PSModules.<ServiceName>
. - Register the extracted directory as the local PowerShell
repository:
PS /> Register-PSRepository -Name "LocalRepo" -SourceLocation <extractedlocation>
- Find the modules available in the local
repository:
PS /> Find-Module -Repository "LocalRepo"
- Install a specific module:
PS /> Install-Module -Name OCI.PSModules.Objectstorage -Verbose -Repository LocalRepo
Note
Each service module depends on theOCI.PSModules.Common
(Common Module), which offers functionalities common to all service modules. Installing a service module will also install the corresponding version ofOCI.PSModules.Common
for that service module. - Installed modules can be found in the path specified by the
$Env:PSModulePath
environment variable, or by running the Get-Module command with theListAvailable
parameter.PS /> Get-Module -ListAvailable
Installing with Yum
If you are using Oracle Linux version 7.x, the OCI PowerShell Modules packages can be installed with yum.
- To install the OCI PowerShell modules using
yum:
$ sudo yum install oci-powershell-modules
- Start a PowerShell Session and register the downloaded directory
/usr/lib/dotnet/NuPkgs as a local PowerShell repository using the
following
command:
$ pwsh PS /> Register-PSRepository -Name "LocalRepo" -SourceLocation /usr/lib/dotnet/NuPkgs
- Find the modules available in the local repository using the following
command:
PS /> Find-Module -Repository "LocalRepo"
- Install a specific module:
PS /> Install-Module -Name OCI.PSModules.Objectstorage -Verbose -Repository LocalRepo
Note
Each service module depends on theOCI.PSModules.Common
(Common Module), which offers functionalities common to all service modules. Installing a service module will also install the corresponding version ofOCI.PSModules.Common
for that service module. - Installed modules can be found in the path specified by the
$Env:PSModulePath
environment variable, or by running the Get-Module command with theListAvailable
parameter.PS /> Get-Module -ListAvailable
Setup
Follow these installation steps if you haven't installed the required modules.
Before invoking cmdlets in OCI Modules, you need to set up the configuration file, and then optionally import the required modules into a PowerShell session.
Configuration File
A configuration file provides essential configuration information, like user credentials and tenancy OCID. This configuration information is used by the OCI Modules for PowerShell to authenticate and interact with Oracle Cloud services. You can create this file using a setup cmdlet, or manually using a text editor.
Set-OCIClientConfig
The Set-OCIClientConfig
cmdlet included in the Common module will walk
you through setting up a configuration file. This cmdlet prompts you for information
required by the configuration file, including the key pair used to sign API requests.
For more information about how to find the required information, see:
Manual Setup
If you want to set up the API signing key pair manually and write your own configuration file, see SDK and Tool Configuration and Required Keys.
Use the New-OCIClientKeys
cmdlet to generate a API signing key pair
to include in the configuration file.
Importing Modules
PowerShell will automatically import the module (and its dependencies) into your session the first time you run any command from the installed module. To explicitly import a module, run the Import-Module command.
For example, to import the version 1.0.0 of the Identity service module:
PS /> Import-Module OCI.PSModules.Identity -RequiredVersion 1.0.0 -Verbose
To find all imported modules in your current PowerShell Session, run the
Get-Module
command:
PS /> Get-Module
ModuleType Name ExportedCommands
---------- ---- ----------------
Binary OCI.PSModules.Common {Clear-OCICmdletHistory, Get-OCIClientSession], Get-OCICmdletHisto…
Binary OCI.PSModules.Identity {Add-OCIIdentityUserToGroup, Enable-OCIIdentityMfaTotpDevice…
Each service module depends on the
OCI.PSModules.Common
(Common
Module), which offers functionalities common to all service modules. Installing a
service module will also install the corresponding version of
OCI.PSModules.Common
for that service module.Updating Modules
New versions of the OCI PowerShell modules release weekly. To update the installed OCI PowerShell modules to the latest version, run the Update-Module command.
Before updating any OCI module, you should first uninstall the module. To avoid dependency conflicts when importing modules into PowerShell session, update all installed OCI Modules to the same version.
PS /> Update-Module -Name "OCI.PSModules.*" -Verbose
Uninstalling Modules
To remove any installed module, you can either use the Uninstall-Module cmdlet or delete the module
folder located in the path in the $Env:PSModulePath
environment
variable.
For example:
PS /> Uninstall-Module -Name OCI.PSModules.Identity
Next Steps
Now that you've taken care of installation and setup, you can proceed directly to Working with Cmdlets, or continue to Advanced Concepts.