1. Platform CLI for Release 1.8
  2. Using the Platform CLI

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 the olcne-api-server service is available. The default port is 8091.

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 or yml. 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 or vault. Use file for certificates saved on the nodes and use vault 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 for type 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.