Skip to content

Commit ea675b3

Browse files
drupanchaldrupanchal
authored
Management Agent container to support runAsUser and --read-only flag (#2615)
1 parent ac577b0 commit ea675b3

File tree

15 files changed

+1095
-180
lines changed

15 files changed

+1095
-180
lines changed

‎OracleManagementAgent/README.md

Lines changed: 112 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -1,161 +1,211 @@
11
# Oracle Management Agent Container Image
2-
This repository contains sample container configurations to facilitate installation and environment setup for DevOps users. This project includes Dockerfiles based on Oracle Linux and Oracle OpenJDK 8.
2+
3+
This repository contains sample container configurations of [Oracle Management Agent](https://docs.oracle.com/en-us/iaas/management-agents/index.html) to facilitate installation and environment setup for DevOps users. This project includes Dockerfiles based on Oracle Linux and Oracle OpenJDK 8.
34

45
The certification of Oracle Management Agent in a container does not require the use of any file presented in this
56
repository. Customers and users are welcome to use them as starters, and customize/tweak, or create
67
from scratch new scripts and Dockerfiles.
78

9+
> Note: The Oracle Management Agent container image no longer requires elevated privileges. You can now chose to create a new user for the agent when building the image or at runtime by providing the UID and GID values of an existing user account on the host system.
810
911
## How to build and run
1012

11-
Oracle Management Agent image uses the official `oraclelinux:7-slim` container image as the base image.
13+
Oracle Management Agent image uses the official `oraclelinux:8-slim` container image as the base image.
1214

13-
#### Prerequisites
15+
## Prerequisites
1416

15-
1. [Download the Management Agent software](https://cloud.oracle.com/macs)
17+
1. [Download the Oracle Management Agent software](https://cloud.oracle.com/macs)
1618

17-
**Note: Select 'Downloads and Keys' then download 'Agent for LINUX (X86_64)' of the package type ZIP.**
19+
> Note: Select 'Downloads and Keys' then download 'Agent for LINUX (X86_64)' of the package type ZIP.
1820
19-
1. Copy the downloaded bundle to the same directory as the Dockerfile
21+
1. Copy the downloaded bundle to the same directory as the `Dockerfile`
2022

2123
```shell
22-
$ cp oracle.mgmt_agent.zip OracleManagementAgent/dockerfiles/latest/
24+
cp oracle.mgmt_agent.zip OracleManagementAgent/dockerfiles/latest/
2325
```
2426

25-
1. Follow the steps in the [Create Install Key](https://docs.oracle.com/en-us/iaas/management-agents/doc/management-agents-administration-tasks.html#GUID-C841426A-2C32-4630-97B6-DF11F05D5712) and [Configure a Response File](https://docs.oracle.com/en-us/iaas/management-agents/doc/install-management-agent-chapter.html#GUID-5D20D4A7-616C-49EC-A994-DA383D172486) sections of the [Management Agent](https://docs.oracle.com/en-us/iaas/management-agents/index.html) documentation to create an install key and save it locally as `input.rsp`.
27+
1. Change to the directory in which the `Dockerfile` for this container image is located
28+
29+
```shell
30+
cd OracleManagementAgent/dockerfiles/latest/
31+
```
2632

27-
1. Copy the downloaded install key to the same directory as the Dockerfile
33+
1. Follow the steps in the [Create Install Key](https://docs.oracle.com/en-us/iaas/management-agents/doc/management-agents-administration-tasks.html#GUID-C841426A-2C32-4630-97B6-DF11F05D5712) documentation to download the install key.
34+
Next, follow the steps to [Configure a Response File](https://docs.oracle.com/en-us/iaas/management-agents/doc/install-management-agent-chapter.html#GUID-5D20D4A7-616C-49EC-A994-DA383D172486) and save it locally as `input.rsp` in the current directory.
35+
36+
1. Create a directory on the host to store persisitent data. This directory will be bind mounted into the container at runtime.
2837

2938
```shell
30-
$ cp input.rsp OracleManagementAgent/dockerfiles/latest/
39+
rm -rf /oracle-management-agent
40+
mkdir -p /oracle-management-agent
3141
```
3242

33-
1. Change to the directory in which the `Dockerfile` for this container image is located
43+
1. Create a local user account that will be used to run the container. This can be any user account on the host system and if the desired user already exists then this step can be skipped.
44+
45+
```shell
46+
groupadd -g 9100 orclmgmtagntgrp
47+
useradd orclmgmtagntusr -u 9200 -g 9100 -m -s /bin/bash
48+
```
49+
50+
> Note: Remember to substitute `orclmgmtagntusr` and `orclmgmtagntgrp`, wherever applicable, with the desired user if you choose to skip this step.
51+
52+
1. Change ownership of the directory holding persistent data to the desired user.
3453

3554
```shell
36-
$ cd OracleManagementAgent/dockerfiles/latest/
55+
chown -R orclmgmtagntusr:orclmgmtagntgrp /oracle-management-agent
3756
```
3857

3958
1. Ensure your tenancy is configured correctly by [applying the documented prerequisites for deploying management agents](https://docs.oracle.com/en-us/iaas/management-agents/doc/perform-prerequisites-deploying-management-agents.html)
4059

41-
#### Steps to build and run using Docker Compose
60+
## Using Docker Compose
61+
62+
1. Create .env file to populate the environment variables
4263

43-
1. Create .env file to populate the hostname variable
4464
```shell
45-
$ echo "mgmtagent_hostname=mgmtagent912" > .env
65+
echo "mgmtagent_hostname=mgmtagentcontainer1" > .env
66+
echo "DOCKER_BASE_DIR=/oracle-management-agent" >> .env
67+
echo "USERID=$(id -u orclmgmtagntusr)" >> .env
68+
echo "GROUPID=$(id -g orclmgmtagntusr)" >> .env
4669
```
47-
**Note: Chose a unique hostname as it will be used to identify Management Agent in the UI.**
4870

4971
1. Use Docker Compose CLI to build and run a container image
5072

5173
```shell
52-
$ docker-compose up -d
74+
docker-compose up --build -d
5375
```
5476

55-
#### Steps to build and run using Docker CLI
77+
## Using Docker or Podman
5678

5779
1. Build the container image
5880

5981
```shell
60-
$ docker build -t oracle/mgmtagent-container .
82+
> docker build -t oracle/mgmtagent-container .
6183
```
6284

63-
1. Create a Docker volume to share configs with the container
85+
1. Copy the Install Key (`input.rsp`) into the directory that will be bind mounted into the container and used for persistent storage
6486

6587
```shell
66-
$ docker volume create mgmtagent-volume
67-
68-
# identify the mount point location to use in next steps
69-
$ docker volume inspect mgmtagent-volume|grep Mountpoint
70-
"Mountpoint": "/var/lib/docker/volumes/mgmtagent-volume/_data",
88+
mkdir -p /oracle-management-agent/mgmtagent_secret/
89+
cp input.rsp /oracle-management-agent/mgmtagent_secret/
90+
chown -R orclmgmtagntusr:orclmgmtagntgrp /oracle-management-agent/mgmtagent_secret/
7191
```
7292

73-
1. Copy the Install Key (input.rsp) into the shared Docker volume Mountpoint
93+
1. Start a container
7494

7595
```shell
76-
# create any necessary dirs
77-
$ mkdir -p /var/lib/docker/volumes/mgmtagent-volume/_data/mgmtagent_secret
78-
$ cp input.rsp /var/lib/docker/volumes/mgmtagent-volume/_data/mgmtagent_secret/
96+
# commands given below expect user to be running in a bash shell
97+
export USERID=$(id -u orclmgmtagntusr)
98+
export GROUPID=$(id -g orclmgmtagntusr)
99+
docker run --user $USERID:$GROUPID -d --name mgmtagentcontainer1 --hostname mgmtagentcontainer1 -v /oracle-management-agent/:/opt/oracle:rw --restart unless-stopped oracle/mgmtagent-container:latest
79100
```
80101

81-
1. Start a container
102+
> Note: Refer to [description of the recommended run parameters](https://docs.docker.com/engine/reference/run) used above
103+
104+
1. Remove the Install Key (`input.rsp`) from the host directory after [verifying the new Oracle Management Agent is registered and visible in the main Oracle Management Agent page](https://docs.oracle.com/en-us/iaas/management-agents/doc/install-management-agent-chapter.html#GUID-46BE5661-012E-4557-B679-6456DBBEAA4A)
82105

83106
```shell
84-
$ docker run -d --name mgmtagent-container --hostname mgmtagent1 -v mgmtagent-volume:/opt/oracle:rw --restart unless-stopped oracle/mgmtagent-container:latest
107+
> rm /oracle-management-agent/mgmtagent_secret/input.rsp
85108
```
86109

87-
**Description of Docker run parameters used above**
88-
<!-- markdownlint-disable MD033 -->
89-
| Parameter | Description |
90-
| --------- | ----------- |
91-
| -d | Starts mgmtagent-container in detached mode |
92-
| --name mgmtagent-container | The name given to the container to identify it. |
93-
| --hostname mgmtagent1 | Assign mgmtagent1 as the containers internal hostname. This can be any hostname compliant string and it will be used to identify the Management Agent instance in the OMC Console. |
94-
| -v mgmtagent-volume | /opt/oracle:rw: Mounts the volume mgmtagent-volume created on host filesystem inside the container at /opt/oracle with Read/Write privileges. |
95-
| --restart unless-stopped | Unless explicitly stopped, this restart policy restarts mgmtagent-container automatically when docker restarts. |
96-
<!-- markdownlint-enable MD033 -->
110+
## Running custom user operations
111+
112+
You can provide a custom shell script that will run before the Oracle Management Agent starts by following these steps
97113

98-
1. Remove the Install Key (input.rsp) from the shared Docker volume Mountpoint after [verifying the new Management Agent is registered and visible in the main Management Agents page](https://docs.oracle.com/en-us/iaas/management-agents/doc/install-management-agent-chapter.html#GUID-46BE5661-012E-4557-B679-6456DBBEAA4A)
114+
1. Refer to [init-agent.sh](dockerfiles/latest/user-scripts/init-agent.sh) in the user-scripts directory
115+
116+
Modify the script `init-agent.sh` to add custom commands that execute each time before Oracle Management Agent starts
117+
118+
1. Follow the steps to build and run a container and validate the output of `init-agent.sh` script is visible in the logs by running the following command
99119

100120
```shell
101-
$ rm /var/lib/docker/volumes/mgmtagent-volume/_data/mgmtagent_secret/input.rsp
121+
> docker logs mgmtagent-container
102122
```
103123

104-
#### Steps to execute custom user operations
124+
## Troubleshooting
105125

106-
Users can provide custom shell script commands to execute before starting Management Agent as described in the following steps
126+
Below are some possible solutions to common issues that may occur when running the Oracle Management Agent in a container
107127

108-
1. Refer to [init-agent.sh](dockerfiles/latest/user-scripts/init-agent.sh) in the user-scripts directory
128+
1. mkdir: cannot create directory '/opt/oracle/bootstrap': Permission denied
109129

110-
Modify the script `init-agent.sh` to add custom commands that execute each time before Management Agent starts
130+
* Ensure the mounted bind volume exists and is accessible by the user used to run the container
131+
* Verify the user USERID and GROUPID used match the permissions set on the mounted bind volume
132+
* Verify the mounted bind volume exists on the host
111133

112-
1. Follow the steps to build and run a container and validate the output of `init-agent.sh` script is visible in the logs by running the following command
134+
1. Invalid argument: /opt/oracle/mgmtagent_secret/input.rsp
135+
136+
* Ensure the install key exists at the required location
137+
138+
1. Oracle Management Agent registration failures due to old state files from a prior install
139+
* Once a Oracle Management Agent instance is deregistered that instance must be shutdown and any associated state files must be removed from the filesystem. Starting a deregistered Oracle Management Agent instance again can result in unregistered agent failures.
140+
This situation can present itself when old state files from a prior installation are present on the filesystem and made available to a new Oracle Management Agent container deployment. Run the command given below on the host filesystem to perform the necessary cleanup on the bind mount location and perform the deployment again starting at the prerequisites step.
113141

114142
```shell
115-
$ docker logs mgmtagent-container
143+
rm -rf /oracle-management-agent/
116144
```
117145

118-
#### Helpful administration commands
146+
## Helpful commands
119147

120-
1. Starting a stopped Management Agent Container
148+
1. Starting a stopped Oracle Management Agent Container
121149

122150
```shell
123-
$ docker start mgmtagent-container
151+
docker start mgmtagent-container
124152
```
125153

126-
1. Stopping a running Management Agent Container
154+
1. Stopping a running Oracle Management Agent Container
127155

128156
```shell
129-
$ docker stop mgmtagent-container
157+
docker stop mgmtagent-container
130158
```
131159

132-
1. Inspecting logs of Management Agent Container
160+
1. Inspecting the logs of a running Oracle Management Agent container
133161

134162
```shell
135-
$ docker logs mgmtagent-container
163+
docker logs mgmtagent-container
136164
```
137165

138-
1. Cleanup volume using Docker Compose
166+
1. Gathering UID and GID of a user from the host environment
139167

140168
```shell
141-
$ docker-compose down --volumes
169+
id -u <username> # prints UID of user
170+
id -g <username> # prints GID of user
142171
```
143172

144-
1. Cleanup volume using Docker CLI
173+
1. Creating a nominated user account during image development (optional)
145174

146175
```shell
147-
$ docker volume rm mgmtagent-volume
176+
groupadd -g <numeric-gid-value> <desired-groupname>
177+
# example:
178+
groupadd -g 9100 orclmgmtagntgrp
179+
180+
useradd <desired-username> -u <numeric-uid-value> -g <numeric-gid-value> -m -s /bin/bash
181+
# example:
182+
useradd orclmgmtagntusr -u 9200 -g 9100 -m -s /bin/bash
183+
184+
# Tip: Add useradd/groupadd to Dockerfile to create a nominated user during image development
148185
```
149186

187+
## Container Files for Older Releases
188+
189+
The Oracle Management Agent older container files mentioned below are no longer actively maintained and they are kept in this repository for historical purposes only.
190+
191+
* Oracle Management Agent container files version 1.0.0 [`docker-images/OracleManagementAgent/dockerfiles/1.0.0`](./dockerfiles/1.0.0)
192+
193+
**Notes:**
194+
195+
* Oracle Management Agent container files version 1.0.0 require elevated privileges to run and therefore are not compatible with the latest version found in this repository. Upgrading a version 1.0.0 container to run with the latest container files is also not supported for the same reason.
196+
150197
## License
198+
151199
To download and run the Oracle Management Agent, regardless whether inside or outside a container, you must download the binaries from the Oracle website and accept the license indicated at that page.
152200

153201
Oracle Linux is licensed under the [Oracle Linux End-User License Agreement](https://oss.oracle.com/ol/EULA).
154202

155-
All scripts and files hosted in this project and GitHub [`docker-images/OracleManagementAgent`](./) repository, required to build the Docker images are, unless otherwise noted, released under the [UPL 1.0](https://oss.oracle.com/licenses/upl/) license.
203+
All scripts and files hosted in this project and GitHub [`docker-images/OracleManagementAgent`](./) repository, required to build the container images are, unless otherwise noted, released under the [UPL 1.0](https://oss.oracle.com/licenses/upl/) license.
156204

157205
## Support
206+
158207
Oracle Management Agent container image is supported for the Linux images listed [here](https://docs.oracle.com/en-us/iaas/management-agents/doc/perform-prerequisites-deploying-management-agents.html#GUID-BC5862F0-3E68-4096-B18E-C4462BC76271). For more details please see My Oracle Support.
159208

160209
## Copyright
161-
Copyright (c) 2022 Oracle and/or its affiliates.
210+
211+
Copyright (c) 2022, 2023 Oracle and/or its affiliates.

‎OracleManagementAgent/dockerfiles/1.0.0/Dockerfile

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Copyright (c) 2023 Oracle and/or its affiliates.
2+
#
3+
# Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl.
4+
#
5+
# ORACLE DOCKERFILES PROJECT
6+
# --------------------------
7+
# This is the Dockerfile for Oracle Management Agent
8+
#
9+
# Base image of this dockerfile is Oracle Linux 7 Slim docker image.
10+
#
11+
# REQUIRED FILES TO BUILD THIS IMAGE
12+
# ----------------------------------
13+
# (1) Management Agent software for Linux (Linux-x86_64/latest/oracle.mgmt_agent.zip)
14+
#
15+
# How to download the Management Agent software:
16+
# https://docs.oracle.com/en-us/iaas/management-agents/doc/install-management-agent-chapter.html
17+
#
18+
# HOW TO BUILD THIS IMAGE
19+
# -----------------------
20+
# Put all downloaded files in the same directory as this Dockerfile
21+
# Run:
22+
# $ docker build -t oracle/mgmtagent-container .
23+
#
24+
# This command is already scripted in build.sh so you can alternatively run
25+
# $ bash build.sh
26+
#
27+
28+
FROM oraclelinux:7-slim
29+
30+
# Labels
31+
LABEL "provider"="Oracle" \
32+
"issues"="https://github.com/oracle/docker-images/issues" \
33+
"volume.data"="/opt/oracle"
34+
35+
# Install packages to install and run Management Agent
36+
RUN set -eux; \
37+
yum -y install \
38+
java-1.8.0-openjdk-devel.x86_64 \
39+
sudo \
40+
unzip \
41+
&& rm -rf /var/cache/yum
42+
43+
# Specify locale settings
44+
ENV LANG en_US.UTF-8
45+
ENV LC_ALL C
46+
47+
# Copy container scripts to initialize the environment and start Management Agent
48+
COPY ./container-scripts/*.sh /opt/oracle-mgmtagent-bootstrap/scripts/
49+
RUN chmod 0544 /opt/oracle-mgmtagent-bootstrap/scripts/*.sh
50+
51+
# Copy user provided scripts
52+
COPY ./user-scripts/init-agent.sh /opt/oracle-mgmtagent-bootstrap/scripts/
53+
RUN chmod 0544 /opt/oracle-mgmtagent-bootstrap/scripts/init-agent.sh
54+
55+
# Copy Management Agent Installer Zip bundle
56+
COPY ./oracle.mgmt_agent.zip /opt/oracle-mgmtagent-bootstrap/packages/
57+
58+
# Set watchdog as the entrypoint script (PID-1) for the container
59+
ENTRYPOINT ["/opt/oracle-mgmtagent-bootstrap/scripts/watchdog.sh"]

0 commit comments

Comments
 (0)