1 Using the Platform CLI
The Oracle Cloud Native Environment Platform CLI,
olcnectl
, is used to configure, deploy, and manage the components of Oracle Cloud Native Environment. The olcnectl
command is
installed using the olcnectl
software package on an operator node. For
information on setting up an operator node, see Installation.
You interact with olcnectl
by entering commands with a series of options.
The Platform CLI syntax is:
olcnectl command [command_options|{-h|--help}]
The full syntax and options for each command is provided in Platform CLI Commands.
When you use the olcnectl
command, you're prompted for any missing options.
Getting Syntax Help
You can get help on the syntax for olcnectl
commands using the
--help
option. For example, to show the command options available for the
olcnectl
command, enter:
olcnectl --help
The output looks similar to:
A CLI that talks to an Oracle Cloud Native Environment Platform API Server endpoint,
facilitating deployment and management of Kubernetes clusters and their resources
Usage:
olcnectl [command]
Available Commands:
certificates X509 certificate management utilities
completion Generate the autocompletion script for the specified shell
environment Environment operations
help Help about any command
module Modules that can be modified in an environment
node Perform Platform configuration on individual compute resources
provision Provisions a complete deployment including Platform components and modules
template Generate a configuration file template
Flags:
-h, --help help for olcnectl
Use "olcnectl [command] --help" for more information about a command.
The Available Commands
section lists any available commands for the
olcnectl
command. In this case, you can use the commands olcnectl
certificates
, olcnectl completion
, olcnectl
environment
, and so on.
The Flags
section lists the available command
options you can use.
The olcnectl help
command is the same as using olcnectl
--help
. It prints the help for the olcnectl
command.
You can drill further down into the help system by providing the --help
option to the commands listed in the Available Commands
section. For example,
to show the available commands and options for the olcnectl module
command,
enter:
olcnectl module --help
The output looks similar to:
Modules that are used to customize your environment
Usage:
olcnectl module [command]
Available Commands:
backup Backup a module
create Create a module
install Install a module
instances List all module instances that are defined in an environment
list Show all modules that can be installed
property Commands that interact with module properties
report Display the report of the selected module instance
restore Restore a module
uninstall Uninstall a module
update Update a module
validate Validate that an module can be installed
version Show version(s) of module(s) that can be installable
Flags:
-a, --api-server string Platform API Server to talk to. If this is not specified, a local instance of the API server will be created for the duration of the command
--config-file string Location of configuration file that contains the optional flags of a command
-h, --help help for module
--olcne-ca-path string Optional path to a predefined CA or the a destination if using a secret manager that will download the CA. Default: /home/opc/.olcne/certificates/<APISERVER_URL>/ca.cert or gathered from the local config (See: '--update-config')
--olcne-node-cert-path string Optional path to a predefined Key or the a destination if using a secret manager that will download the Key. Default: /home/opc/.olcne/certificates/<APISERVER_URL>/node.key or gathered from the local config (See: '--update-config')
--olcne-node-key-path string Optional path to a predefined Cert or the a destination if using a secret manager that will download the Cert. Default: /home/opc/.olcne/certificates/<APISERVER_URL>/node.cert or gathered from the local config (See: '--update-config')
...
Use "olcnectl module [command] --help" for more information about a command.
Again, the Available Commands
section lists any sub commands available for
the command. In this case, you can use commands such as olcnectl module
backup
, olcnectl module create
, olcnectl module
install
, and so on.
The Flags
section lists the options that can be
used by all subcommands.
Drilling further down into the help system you can see the olcnectl module
property
command has a further two options, get
and
list
.
olcnectl module property --help
The output looks similar to:
Commands that interact with module properties
Usage:
olcnectl module property [command]
Available Commands:
get Gets the value of one or more properties
list Show all properties for a module
Flags:
-h, --help help for property
Global Flags:
-a, --api-server string Platform API Server to talk to. If this is not ...
--config-file string Location of configuration file that contains ...
--olcne-ca-path string Optional path to a predefined CA or the a ...
...
Use "olcnectl module property [command] --help" for more information about a command.
A new set of command options is listed under The Global Flags
section. The
options shown in this section are global flags, which are used by all
olcnectl
subcommands. For more information on global flags, see Using Global Flags.
To get a list of the command options, you need to include the full command with the
--help
option. In this case, the olcnectl module property
get
command has four options as shown in the Flags
section.
olcnectl module property get --help
The output looks similar to:
Given a list of properties, fetch the value of each for a specific module
Usage:
olcnectl module property get [flags]
Flags:
-E, --environment-name string Name of the environment
-h, --help help for get
-N, --name string Name of the module
-P, --property strings Names of properties to fetch
...
The help system for the olcnectl module create
and the olcnectl
module update
commands behaves differently to the other uses of the
--help
option. As many modules can be within an environment, you must
provide information about a module in order for the Platform CLI to display the appropriate
help. To display the help for the olcnectl module create
command, enter:
olcnectl module create --help
The output looks similar to:
Create a module in a environment
Usage:
olcnectl module create [flags]
Flags:
-E, --environment-name string Name of the environment
-h, --help help for create
-M, --module strings Module to create
-N, --name strings Name to assign the module
...
To see the options for creating each module you must use the
--module
option and provide the module type.
The module types are listed in
Module Create. For example, to get help
on creating a Kubernetes module you specify the
module type as kubernetes
:
olcnectl module create --module kubernetes --help
The output looks similar to:
Create a module in a environment
Usage:
olcnectl module create [flags]
Flags:
-b, --apiserver-bind-port string Kubernetes API Server bind port (default "6443")
-B, --apiserver-bind-port-alt string Port for the Kubernetes API Server to bind to if a virtual-ip is used (default "6444")
-e, --apiserver-cert-extra-sans string Kubernetes API Server extra sans
--compact string Allow workloads to be deployed on control-plane nodes (default "false")
-r, --container-registry string Container Registry that holds the kubernetes images
-c, --control-plane-nodes string A comma separated list of control-plane nodes
-E, --environment-name string Name of the environment
-h, --help help for create
-x, --kube-proxy-mode string Routing mode for the Kubernetes proxy (default "iptables")
--kube-tls-cipher-suites string TLS Cipher for kubernetes
--kube-tls-min-version string TLS Minimum Version for kubernetes (default "VersionTLS12")
-v, --kube-version string Kubernetes version (default "1.28.8")
-t, --kubeadm-token string kubeadm token used to join nodes
-l, --load-balancer string API Server load balancer IP address
-M, --module strings Module to create
-N, --name strings Name to assign the module
...
Similarly, to get help on the olcnectl module update
command use:
olcnectl module update --help
The output looks similar to:
Update a module
Usage:
olcnectl module update [flags]
Flags:
-E, --environment-name string Name of the environment
-F, --force Update without prompting
-g, --generate-scripts Generate a script for each node that takes all suggested actions
-h, --help help for update
-N, --name strings Modules to update
...
The output shows a --name
option. This is the option you use to specify the
module. This example shows the output for the olcnectl module update --help
command for a Kubernetes module named mycluster
:
olcnectl module update --environment-name myenvironment --name mycluster --help
The output looks similar to:
Update a module
Usage:
olcnectl module update [flags]
Flags:
--compact string Allow workloads to be deployed on control-plane nodes (default "false")
-r, --container-registry string Container Registry that holds the kubernetes images
-c, --control-plane-nodes string A comma separated list of control-plane nodes
-E, --environment-name string Name of the environment
-F, --force Update without prompting
-g, --generate-scripts Generate a script for each node that takes all suggested actions
-h, --help help for update
-v, --kube-version string Kubernetes version (default "1.28.8")
-N, --name strings Modules to update
...
The output shows the options you can use to scale or update/upgrade the Kubernetes module.
Setting the Platform API Server
The Platform CLI connects to an Oracle Cloud Native Environment Platform
API Server. You can use an operator node with the Platform CLI installed to connect to many
Platform API Server instances. You specify the Platform API Server using the olcnectl
--api-server api_server_address:8091
option. This lets you use a
single operator node to manage many environments. For example, to connect to a Platform API
Server on apiserver.example.com
, you would use:
olcnectl module property list \
--api-server apiserver.example.com:8091 \
--environment-name myenvironment \
--name mycluster
When you create an environment with the olcnectl environment create
command you can optionally include the --update-config
option. This option
writes information about the environment to a local configuration file at
$HOME/.olcne/olcne.conf
, and this configuration is used for future calls to
the Platform API Server. If you use this option, you don't need to specify the Platform API
Server in future olcnectl
commands.
For example, if you create an environment using the
--update-config
option:
olcnectl environment create \
--api-server 127.0.0.1:8091 \
--environment-name myenvironment \
--secret-manager-type vault \
--vault-token s.3QKNuRoTqLbjXaGBOmO6Psjh \
--vault-address https://192.0.2.20:8200 \
--update-config
When you write all future olcnectl
commands you
can omit the --api-server
option. For example:
olcnectl module property list \
--environment-name myenvironment \
--name mycluster
You can also set an environment variable to set the
Platform API Server. You can do this using the
$OLCNE_API_SERVER_BIN
environment variable on
the operator node. For example, to set the Platform API Server to
the localhost, use:
export OLCNE_API_SERVER_BIN=127.0.0.1:8091
Using Global Flags
Global flags can be used with all olcnectl
commands. These options are most
often used when creating an environment using the olcnectl environment create
command, however they can also be used with all other olcnectl
commands. The
global options are:
[{-a|--api-server} api_server_address:8091]
[--config-file path]
[--secret-manager-type {file|vault}]
[--update-config]
[--olcne-ca-path ca_path]
[--olcne-node-cert-path node_cert_path]
[--olcne-node-node-key-path node_key_path]
[--olcne-tls-cipher-suites ciphers]
[--olcne-tls-max-version version]
[--olcne-tls-min-version version]
[--vault-address vault_address]
[--vault-cert-sans vault_cert_sans]
[--vault-token vault_token]
Where:
-
{-a|--api-server} api_server_address:8091
-
The Platform API Server for the environment. This is the host running the
olcne-api-server
service in an environment. The value of api_server_address is the IP address or hostname of the Platform API Server. The port number is the port on which theolcne-api-server
service is available. The default port is8091
.If a Platform API Server isn't specified, a local instance is used. If no local instance is set up, it's configured in the
$HOME/.olcne/olcne.conf
file.For more information on setting the Platform API Server see Setting the Platform API Server.
This option maps to the
$OLCNE_API_SERVER_BIN
environment variable. If this environment variable is set it takes precedence over and overrides the Platform CLI setting. -
--config-file path
-
The location of a YAML file that contains the configuration information for the environments and modules. The filename extension must be either
yaml
oryml
. When you use this option, any other command line options are ignored, except the--force
option. Only the information contained in the configuration file is used. -
--secret-manager-type {file|vault}
-
The secrets manager type. The options are
file
orvault
. Usefile
for certificates saved on the nodes and usevault
for certificates managed by Vault. -
--update-config
-
Writes the global arguments for an environment to a local configuration file which is used for future calls to the Platform API Server. If this option hasn't been used before, global arguments must be specified for every Platform API Server call.
The global arguments configuration information is saved to
$HOME/.olcne/olcne.conf
on the local host.If you use Vault to generate certificates for nodes, the certificate is saved to
$HOME/.olcne/certificates/environment_name/
on the local host. -
--olcne-ca-path ca_path
-
The path to a predefined Certificate Authority certificate, or the destination of the certificate if using a secrets manager to download the certificate. The default is
/etc/olcne/certificates/ca.cert
, or gathered from the local configuration if the--update-config
option is used.This option maps to the
$OLCNE_SM_CA_PATH
environment variable. If this environment variable is set it takes precedence over and overrides the Platform CLI setting. -
--olcne-node-cert-path node_cert_path
-
The path to a predefined certificate, or the a destination if using a secrets manager to download the certificate. The default is
/etc/olcne/certificates/node.cert
, or gathered from the local configuration if the--update-config
option is used.This option maps to the
$OLCNE_SM_CERT_PATH
environment variable. If this environment variable is set it takes precedence over and overrides the Platform CLI setting. -
--olcne-node-key-path node_key_path
-
The path to a predefined key, or the destination of the key if using a secrets manager to download the key. The default is
/etc/olcne/certificates/node.key
, or gathered from the local configuration if the--update-config
option is used.This option maps to the
$OLCNE_SM_KEY_PATH
environment variable. If this environment variable is set it takes precedence over and overrides the Platform CLI setting. -
--olcne-tls-cipher-suites ciphers
-
The TLS cipher suites to use for Oracle Cloud Native Environment services (the Platform Agent and Platform API Server). Enter one or more in a comma separated list. The options are:
-
TLS_AES_128_GCM_SHA256
-
TLS_AES_256_GCM_SHA384
-
TLS_CHACHA20_POLY1305_SHA256
-
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
-
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
-
TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
-
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
-
TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
-
TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305
-
TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
-
TLS_ECDHE_ECDSA_WITH_RC4_128_SHA
-
TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
-
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
-
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
-
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
-
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
-
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
-
TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305
-
TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
-
TLS_ECDHE_RSA_WITH_RC4_128_SHA
-
TLS_RSA_WITH_3DES_EDE_CBC_SHA
-
TLS_RSA_WITH_AES_128_CBC_SHA
-
TLS_RSA_WITH_AES_128_CBC_SHA256
-
TLS_RSA_WITH_AES_128_GCM_SHA256
-
TLS_RSA_WITH_AES_256_CBC_SHA
-
TLS_RSA_WITH_AES_256_GCM_SHA384
-
TLS_RSA_WITH_RC4_128_SHA
For example:
--olcne-tls-cipher-suites TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
This option maps to the
$OLCNE_TLS_CIPHER_SUITES
environment variable. If this environment variable is set it takes precedence over and overrides the Platform CLI setting. -
-
--olcne-tls-max-version version
-
The TLS maximum version for Oracle Cloud Native Environment components. The default is
VersionTLS12
. Options are:-
VersionTLS10
-
VersionTLS11
-
VersionTLS12
-
VersionTLS13
This option maps to the
$OLCNE_TLS_MAX_VERSION
environment variable. If this environment variable is set it takes precedence over and overrides the Platform CLI setting. -
-
--olcne-tls-min-version version
-
The TLS minimum version for Oracle Cloud Native Environment components. The default is
VersionTLS12
. Options are:-
VersionTLS10
-
VersionTLS11
-
VersionTLS12
-
VersionTLS13
This option maps to the
$OLCNE_TLS_MIN_VERSION
environment variable. If this environment variable is set it takes precedence over and overrides the Platform CLI setting. -
-
--vault-address vault_address
-
The IP address of the Vault instance. The default is
https://127.0.0.1:8200
, or gathered from the local configuration if the--update-config
option is used. -
--vault-cert-sans vault_cert_sans
-
Subject Alternative Names (SANs) to pass to Vault to generate the Oracle Cloud Native Environment certificate. The default is
127.0.0.1
, or gathered from the local configuration if the--update-config
option is used. -
--vault-token vault_token
-
The Vault authentication token.
Setting up Command Line Completion
You can set up command line completion for the olcnectl
command. Use the
olcnectl completion
command to generate a command line completion
script for the shell. For example, to generate a command line completion script for the
Bash shell on Oracle Linux, run:
olcnectl completion bash
The generated command line completion script must be saved at
/etc/bash_completion.d/olcnectl
.
You can generate the script and save it to the correct location using:
olcnectl completion bash | sudo tee /etc/bash_completion.d/olcnectl
You need to start a new shell session for this setup to take effect. This setup also
requires the bash-completion
package to be installed on the system.
Using Operation Logs
An operation is an encapsulation of a long-running process on the Platform API Server. An
example of an operation is installing a module. For each long-running process, an operation
is created. This object maintains the state of the process, and details of the operation can
be retrieved at any point during its lifecycle. An operation persists, and can be interacted
with, until the process it represents is performed again. You can view the status of the
most recent invocation of some long running Platform CLI commands. For example, you can run
the olcnectl module update
command to update a module, and view the status
of that operation while the operation is happening, and after the operation has completed.
If you run the olcnectl module update
command again for the module, the
previous operation is discarded when the module instance is updated again. Only the latest
iteration of the operation is retained.
You can view the logs for operations using the Platform CLI. You can list all existing operations, follow the logs of ongoing operations, and view the log of an ongoing or completed operation. The operation logs are identical to the logs displayed by the command as it's run, and includes error messages, and suggested user actions.
An operation can be performed by more than one user at the same time. From the perspective
of each user, their invocation is the canonical one. For example, two users can run
olcnectl module install --environment-name myenvironment --name mycluster
in sequence. The first invocation starts the operation, and the second attaches to the
ongoing operation. All log output and exit codes are identical.
Operation logs are created for the following Platform CLI commands:
-
olcnectl module backup
-
olcnectl module install
-
olcnectl module restore
-
olcnectl module uninstall
-
olcnectl module update
-
olcnectl module validate
By default the logging level for operations is set to log error type messages. You can change the type of messages in the logs using the the following syntax option for these commands:
-
{-L|--log-level} type
-
Sets the type of messages displayed by the Platform API Server. If you don't set this option,
error
messages are displayed by default. The options fortype
are:-
error
: Displays error messages. This is the default type. -
warn
: Displays warning messages. -
info
: Displays information messages. -
debug
: Displays all messages. This is the most detailed message level.
-
Setting the log level for a Platform CLI command is distinct from the configured log level
for the Platform API Server. The Platform API Server can be configured to log at an
info
level, but these Platform CLI commands can be configured to provide
debug logging. Setting the logging level for these Platform CLI commands doesn't impact or
affect the logs recorded to the olcne-api-server.service
journal.
All operation state, including identifiers, logs, and so on, are retained only in memory. When the Platform API Server restarts, the information from the previous execution isn't retained. Logs are overwritten when a duplicate of a previous operation is performed again. This prevents resource exhaustion both on-disk and and in memory.
Example 1-1 Setting the Log Level
To set the logging level, use the --log-level
option. For example, to set
the log level to info
when uninstalling a module named
mycluster
in the environment named myenvironment
:
olcnectl module uninstall \
--environment-name myenvironment \
--name mycluster \
--log-level info
As the command runs and the module is uninstalled, the logging information is displayed to the terminal. The output looks similar to:
time level=info msg=Uninstalling instance mycluster of module kubernetes from myenvironment
time level=info msg=Instance mycluster of module kubernetes has been uninstalled from myenvironment
time level=info msg=Uninstalling instance worker1.example.com:8090 of module node from myenvironment
time level=info msg=Instance worker1.example.com:8090 of module node has been uninstalled from myenvironment
...
Modules uninstalled successfully.
The log is also saved to an operation log, running in memory. Each time you run the same command, the operation log is overwritten. Only the last version of the log is available.
Example 1-2 Listing Operation Logs
To list the operation logs that are running or have been completed, use the
olcnectl operation list
command.
olcnectl operation list
The output displays the operation logs that are running and completed and looks similar to:
ID STATUS START TIME END TIME DESCRIPTION
10246902201905982060 Complete date date validating mycluster within myenvironment
4286672629392180085 Running date uninstalling mycluster within myenvironment
17271808965078568352 Complete date date installing mycluster within myenvironment
Example 1-3 Following Operation Logs
To follow the operation log for a running operation, use the olcnectl operation
follow
command. You can get the operation identifier by listing the operations.
For example:
olcnectl operation follow --operation-id 4286672629392180085
The logs for the operation are displayed in real time as they're generated. For example:
...
time level=info msg=Uninstalling instance mycluster of module kubernetes from myenvironment
time level=info msg=Instance mycluster of module kubernetes has been uninstalled from myenvironment
...
Example 1-4 Displaying an Operation Log
To display the operation log for a completed operation, use the olcnectl operation
logs
command. You can get the operation identifier by listing the operations. For
example:
olcnectl operation logs --operation-id 4286672629392180085
The output looks similar to:
time level=info msg=Uninstalling instance mycluster of module kubernetes from myenvironment
time level=info msg=Instance mycluster of module kubernetes has been uninstalled from myenvironment
time level=info msg=Uninstalling instance worker1.example.com:8090 of module node from myenvironment
time level=info msg=Instance worker1.example.com:8090 of module node has been uninstalled from myenvironment
...
Modules uninstalled successfully.