Skip to content

Commit c5e3e43

Browse files
DjelibeybiDjelibeybi
authored
Add OCI CLI container image and documentation (#2409)
* Add OCI CLI container image and documentation * ci: added workflow to build the OCI CLI image Signed-off-by: Avi Miller <avi.miller@oracle.com>
1 parent 1173c03 commit c5e3e43

File tree

4 files changed

+192
-10
lines changed

4 files changed

+192
-10
lines changed

‎.github/workflows/build-and-push-oci-cli-image.yml

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
name: Build and Push Docker Image
2+
3+
on:
4+
push:
5+
branches: [ "main" ]
6+
paths:
7+
- 'OracleCloudInfrastructuree/oci-cli/*'
8+
- '.github/workflows/build-and-push-oci-cli-image.yml'
9+
workflow_dispatch:
10+
pull_request:
11+
branches: [ "main" ]
12+
13+
14+
env:
15+
REGISTRY: ghcr.io
16+
zIMAGE_NAME: 'oracle/oci-cli'
17+
18+
jobs:
19+
build:
20+
21+
runs-on: ubuntu-latest
22+
permissions:
23+
contents: read
24+
packages: write
25+
26+
steps:
27+
- name: Checkout repository
28+
uses: actions/checkout@v3
29+
30+
- name: Set up QEMU
31+
uses: docker/setup-qemu-action@v2
32+
33+
- name: Setup Docker Buildx
34+
uses: docker/setup-buildx-action@v2
35+
36+
- name: Log into registry ${{ env.REGISTRY }}
37+
if: github.event_name != 'pull_request'
38+
uses: docker/login-action@v2
39+
with:
40+
registry: ${{ env.REGISTRY }}
41+
username: ${{ github.actor }}
42+
password: ${{ secrets.GITHUB_TOKEN }}
43+
44+
- name: Extract Docker metadata
45+
id: meta
46+
uses: docker/metadata-action@v4
47+
with:
48+
images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
49+
50+
- name: Build and push image
51+
id: build-and-push
52+
uses: docker/build-push-action@v3
53+
with:
54+
context: .
55+
push: ${{ github.event_name != 'pull_request' }}
56+
platforms: linux/amd64, linux/arm64
57+
tags: ${{ steps.meta.outputs.tags }}
58+
labels: ${{ steps.meta.outputs.labels }}

‎OracleCloudInfrastructure/README.md

Lines changed: 3 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,6 @@
1-
# Oracle Cloud Infrastructure Tools
1+
# Oracle Cloud Infrastructure Container Images
22

3-
The Docker images in this location can be used to create containers that
4-
contain various command-line utilities to interact with Oracle Cloud
5-
Infrastructure (OCI).
6-
7-
## Tools
8-
9-
The following tools are available as Docker images:
3+
The following Oracle Cloud Infrastructure tools are available as container images:
104

5+
* [OCI Command Line Interface](oci-cli/)
116
* [OCI Provider for Terraform](terraform-oci/)
12-
13-

‎OracleCloudInfrastructure/oci-cli/Dockerfile

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Copyright (c) 2022 Oracle and/or its affiliates.
2+
# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl.
3+
4+
FROM ghcr.io/oracle/oraclelinux8-python:3.6
5+
6+
RUN python3 -m pip install --upgrade pip \
7+
&& python3 -m pip install oci-cli \
8+
&& cp /usr/local/lib/python3.6/site-packages/oci_cli/bin/oci_autocomplete.sh /usr/local/bin/oci_autocomplete.sh \
9+
&& chmod +x /usr/local/bin/oci_autocomplete.sh \
10+
&& useradd -m -d /oracle oracle \
11+
&& echo '[[ -e "/usr/local/bin/oci_autocomplete.sh" ]] && source "/usr/local/bin/oci_autocomplete.sh"' >> /oracle/.bashrc
12+
13+
WORKDIR /oracle
14+
USER oracle
15+
16+
ENTRYPOINT ["oci"]
17+
CMD ["--help"]

‎OracleCloudInfrastructure/oci-cli/README.md

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# Oracle Cloud Infrastructure Command Line Interface Container Image
2+
3+
The Oracle Cloud Infrastructure (OCI) Command Line Interface (CLI) is a small-footprint tool that you can use on its own or with the Oracle Cloud Console to complete tasks. The OCI CLI provides the same core functionality as the console, plus additional commands. Some of these, such as the ability to run scripts, extend console functionality.
4+
5+
## Using the OCI CLI container image
6+
7+
To use the OCI CLI container image, you must have:
8+
9+
* a standards-compliant container runtime engine, e.g. [Docker][6], [Podman][7] or similar
10+
* an Oracle Cloud Infrastructure tenancy
11+
* a user account in that tenancy that belongs to a group to which appropriate policies have been assigned to grant the required permissions.
12+
* A keypair used for signing API requests, with the public key uploaded to Oracle. Only the user calling the API should possess the private key. See [Configuring the CLI][3].
13+
14+
For examples of how to set up a new user, group, compartment, and policy, see the [documentation on adding users][1]. For a list of other typical OCI policies, review the [list of common policies][2].
15+
16+
> Oracle recommends creating and using dedicated service accounts instead of personal user accounts for accessing the OCI API.
17+
18+
To use the container image, pull the latest version from the GitHub Container Registry:
19+
20+
```shell
21+
$ docker pull ghcr.io/oracle/oci-cli:latest
22+
$ docker images
23+
REPOSITORY TAG IMAGE ID CREATED SIZE
24+
ghcr.io/oracle/oci-cli latest 387639e80a9a 3 days ago 711MB
25+
```
26+
Consider tagging the image as `oci` to make it a more seamless drop-in replacement:
27+
28+
```shell
29+
$ docker tag ghcr.io/oracle/oci-cli:latest oci
30+
$ docker images oci
31+
REPOSITORY TAG IMAGE ID CREATED SIZE
32+
oci latest 387639e80a9a 3 days ago 711MB
33+
$ docker run -v "$HOME/.oci:/oracle/.oci" oci os ns get
34+
{
35+
"data": "demo-tenancy"
36+
}
37+
```
38+
39+
To make it even easier, create an shell alias that runs the container for you:
40+
41+
```shell
42+
$ alias oci='docker run --rm -it -v "$HOME/.oci:/oracle/.oci" oci'
43+
$ oci os ns get
44+
{
45+
"data": "demo-tenancy"
46+
}
47+
```
48+
49+
## API signing key authentication
50+
51+
This is the default authentication method used by all OCI SDKs and the OCI CLI. To use this method, mount a location on the host system to the `/oracle/.oci` directory inside the container.
52+
53+
If you have previously configured the OCI CLI on the host machine, the easiest way to provide access to your API signing key is map your `$HOME/.oci` directory to `/oracle/.oci/` inside the container:
54+
55+
```shell
56+
$ docker run --rm -it -v "$HOME/.oci:/oracle/.oci" ghcr.io/oracle/oci os ns get
57+
{
58+
"data": "example"
59+
}
60+
```
61+
62+
Alternatively, you could pass the `OCI_CLI_CONFIG_FILE` environment variable to use a different location for the OCI CLI `config` file.
63+
64+
> Note: ensure that the `key_file` field in `$HOME/.oci/config` uses the `~` character so that the path resolves both inside and outside the container, e.g. `key_file=~/.oci/oci_api_key.pem`. Alternatively, pass the `OCI_CLI_KEY_FILE` environment variable to the container at runtime to specify a different location for the private key.
65+
66+
If you haven't previously configured the OCI CLI, create `$HOME/.oci` first then start the OCI CLI's interactive setup process:
67+
68+
```shell
69+
$ mkdir $HOME/.oci
70+
$ docker run --rm -it -v "$HOME/.oci:/oracle/.oci" ghcr.io/oracle/oci-cli setup config
71+
This command provides a walkthrough of creating a valid CLI config file.
72+
...
73+
```
74+
75+
## Session token authentication
76+
77+
To use token-based authentication, map port 8181 to the container:
78+
79+
```shell
80+
docker run --rm -it -v "$HOME/.oci:/oracle/.oci" -p 8181:8181 oci session authenticate
81+
```
82+
83+
## Instance principal authentication
84+
85+
Include the `--auth instance_principal` when running the container to enable instance principal authentication.
86+
87+
```shell
88+
$ docker run --rm -it -v "$HOME/.oci:/oracle/.oci" oci --auth instance_principal os ns get
89+
{
90+
"data": "example"
91+
}
92+
```
93+
94+
If you created a shell alias, add it to the alias definition.
95+
96+
## Building the image locally
97+
98+
To build the image, clone this repository, change to the `OracleCloudInfrastructure/oci-cli` directory and then run:
99+
100+
```shell
101+
docker build --tag oci .
102+
```
103+
104+
## License
105+
106+
This container image is licensed under the Universal Permissive License 1.0. The OCI CLI and samples are dual-licensed under the Universal Permissive License 1.0 and the Apache License 2.0; third-party dependencies are separately licensed as described in the [OCI CLI repository][5].
107+
108+
[1]: https://docs.oracle.com/en-us/iaas/Content/GSG/Tasks/addingusers.htm#Adding_Users
109+
[2]: https://docs.oracle.com/en-us/iaas/Content/Identity/Concepts/commonpolicies.htm#top
110+
[3]: https://docs.oracle.com/en-us/iaas/Content/API/Concepts/apisigningkey.htm#Required_Keys_and_OCIDs
111+
[4]: https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/clitoken.htm#Tokenbased_Authentication_for_the_CLI
112+
[5]: https://github.com/oracle/oci-cli
113+
[6]: https://www.docker.com/
114+
[7]: https://podman.io/

0 commit comments

Comments
 (0)