4.10. Building and Deploying With the kubectl Plugin
When to Use It
- When you want to rebuild a build config created in the Console with a single command
- When embedding build and deployment in an automation script or a CI pipeline
- When checking build status across several namespaces at once
kubectl cop is a kubectl plugin. It does from the command line what the Build menu of the Console does:
creating build configs, starting builds, viewing logs, and deploying.
It uses the same resources as the Console. A build config created by command appears in the Console under Build > Build Configs just as it is, and a build config created in the Console can be built by command. Either starting point works, and you can switch between them at any time.
This differs from the Bastion scripts in 4.5. Those scripts run the S2I tooling on the Bastion itself, whereas this plugin runs the build inside the cluster — the same way the Console does.
Screens and Their Commands
| Console | Command | What it does |
|---|---|---|
| Apply on the build config form (see 4.2) | new-build | Creates the build config and a Deployment with zero pods |
| Start Build | start-build | Creates the build Job |
| Deploy | deploy | Deploys the image from a successful build |
| The three above in sequence | new-app | Creates, builds, and deploys in one go |
The commands use the connection details and permissions of the current kubeconfig as they are. There is no separate sign-in step, and a permission the kubeconfig account lacks is unavailable from the command line as well (see 7.1).
Confirming the Installation
It is installed on the Bastion together with COP. Two commands confirm it.
kubectl plugin list
kubectl cop version
If kubectl-cop appears in kubectl plugin list and kubectl cop version prints a version, it is ready. If the
command is reported as not found, ask the staff who performed the installation.
Command Forms
The official form is kubectl cop <command>, and dropping cop gives the same behavior.
kubectl cop start-build sample-app -n egov # official form
kubectl start-build sample-app -n egov # short form, same behavior
The examples in this chapter use the short form. Ten names can be used without cop.
new-app · new-build · start-build · cancel-build · builds · buildconfigs · bc ·
builders · deploy · build-logs
Two names collide with built-in kubectl commands. kubectl looks for its own commands before plugins, so logs and version use the names below.
| What you want | Command to use | What not to use |
|---|---|---|
| View build logs | kubectl build-logs or kubectl cop logs | kubectl logs — the built-in kubectl command runs |
| View the plugin version | kubectl cop version | kubectl version — the cluster version is printed |
The examples in this chapter use the egov namespace and the sample-app build config, as in 4.1. The
namespace is given with -n on every command.
Creating Something New
There are two commands for creating a build config.
| Command | What it does |
|---|---|
new-build | Creates the build config only. It does not start a build |
new-app | Creates the build config, builds it while showing the log, and deploys if the build succeeds |
Specifying the Builder Image and the Git URL
There are two forms, and the result is the same. <builder>~<git-uri> joins the two with a tilde (~).
# builder and Git URL joined with '~'
kubectl new-build registry.openmaru.io/images/openjdk8-ubi8-s2i-openmaru:latest~http://bitbucket.example.com/scm/sample-app.git \
--source-secret git --push-secret default-registry-secret -n egov
# builder as an option
kubectl new-build http://bitbucket.example.com/scm/sample-app.git \
--builder registry.openmaru.io/images/openjdk8-ubi8-s2i-openmaru:latest \
--source-secret git --push-secret default-registry-secret -n egov
The command below lists the builder images available. They are the same values as the Builder image dropdown on the Console build config form (see 4.2).
kubectl builders
To create and deploy in one go, use new-app.
kubectl new-app registry.openmaru.io/images/openjdk8-ubi8-s2i-openmaru:latest~http://bitbucket.example.com/scm/sample-app.git \
--source-secret git --push-secret default-registry-secret -n egov
Commonly Used Options
The options below exist on both new-build and new-app. The middle column is the field on the Console build config
screen that the value corresponds to.
| Option | Console field | Description |
|---|---|---|
--name | Name | Omitted, the Git repository name is used |
--to | Output image | Omitted, <default registry>/apps/<namespace>/<name> |
--ref | Branch or tag | Omitted, the default branch |
--context-dir | Subdirectory | To build a subdirectory inside the repository |
--env K=V | Build environment variables | Can be given more than once. For the values, see 4.9 |
--source-secret | Source credentials | The Secret name for the Git connection |
--push-secret | Push credentials | The Secret name for the registry connection |
--pull-secret | Builder credentials | When pulling the builder image requires authentication |
--tag-strategy | Tag policy | GitRef (default) or Unique. For the difference, see 4.2 |
--target | The name of the target Deployment | Omitted, the same as the build config name |
--cache-pvc | Advanced options > Volumes | In <PVC name>:<mount path> form. On shortening build time, see 4.2 |
--force | — | Proceeds even when a Deployment belongs to another build config |
Two options exist only on new-app.
| Option | Description |
|---|---|
--no-deploy | Stops after the build without deploying. Deploy later with deploy |
--no-follow | Does not print the log |
An example specifying the cache volume and the deploy target name as well.
kubectl new-build registry.openmaru.io/images/openjdk8-ubi8-s2i-openmaru:latest~http://bitbucket.example.com/scm/sample-app.git \
--source-secret git --push-secret default-registry-secret \
--cache-pvc maven-m2-cache:/home/jboss/.m2 --target sample-app-web -n egov
Building and Deploying
Once the build config exists, the sequence below repeats. It is the same as alternating between Start Build and Deploy in the Console.
| Order | Command | When you use it |
|---|---|---|
| 1 | start-build | After changing and committing the source |
| 2 | builds | To check whether the build has finished |
| 3 | build-logs | To see progress or the cause of a failure |
| 4 | cancel-build | To stop a build in progress |
| 5 | deploy | To deploy a successful build |
Starting a Build
kubectl start-build sample-app -n egov
It creates the build Job and returns immediately. To wait until it finishes, add an option.
| Option | Behavior |
|---|---|
--follow | Prints the log and waits until the build finishes |
--wait | Waits until the build finishes without printing the log |
kubectl start-build sample-app -n egov --follow
When a build fails, the failed stage and the reason are printed. Without --follow, the last part of the failed
container's log is printed as well.
Checking the History
kubectl builds sample-app -n egov
The build name, stage, created image, and start time are printed. It is the same content as the Console build list (see 4.3). Omitting the build config name shows every build in the namespace.
Viewing Logs
kubectl build-logs sample-app -n egov
A build has three stages — git-clone, assemble, and s2i-build — and the command prints them in that order.
Compilation and packaging output appears in the assemble stage. What each stage does is described in
4.3.
| Option | Behavior |
|---|---|
-f | Keeps receiving the log of a build in progress |
-c <stage> | Shows one stage only: git-clone, assemble, or s2i-build |
kubectl build-logs sample-app -n egov -f -c assemble
A build name can be given in place of the build config name, in which case the log of that build is shown.
Cancelling a Build
kubectl cancel-build sample-app -n egov
With no build in progress, it reports that and does nothing.
Deploying
kubectl deploy sample-app -n egov
It deploys the image from the most recent successful build. If the Deployment does not exist it is created; if it does, the image is replaced. When the image carries exposed port information, an access path (Service) is created once as well.
To deploy a specific build, name it.
kubectl deploy sample-app -n egov --build build-sample-app-20260916103000-ab12
Listing
The Build Config List
kubectl bc -n egov
Each build config is one line with the Git URL, output image, last build, and deployment status. The STATUS column
is the result of comparing the image of the most recent successful build with the image currently deployed.
| STATUS | Meaning |
|---|---|
| 최신 (up to date) | The most recent successful build is what is deployed |
| 다름 (differs) | A build was made but not yet deployed. The same as "latest build not deployed" in the Console |
| 미배포 (not deployed) | The target Deployment does not exist yet |
| 빌드 없음 / 성공한 빌드 없음 (no build / no successful build) | There is no image to deploy |
| 비교 불가 (빌드 이미지 기록 없음) (cannot compare) | See the last row of "Things You Run Into" below |
To see several namespaces at once, add -A. The same applies to builds.
kubectl bc -A
Listing With Plain kubectl
The standard commands can list the same things without the plugin.
kubectl get buildconfigs.build.openmaru.io -n egov
kubectl logs job/build-sample-app-20260916103000-ab12 -n egov --all-containers
If you know the build name, the log can be viewed as above. Without --all-containers, only the last stage
(s2i-build) is printed.
Things You Run Into
| Symptom | Cause | Action |
|---|---|---|
| "빌더 이미지를 지정하세요" printed with a list | No builder was given | Choose one from the printed list and run again. The list is the same as kubectl builders |
| Ends with "진행 중인 빌드가 있습니다: ..." (exit code 2) | A build of the same build config is already running | Wait for it, or cancel it with cancel-build and start again |
"default" 네임스페이스에는 빌드·배포 리소스를 만들 수 없습니다 | -n was omitted, or default was given | Give the application namespace with -n |
| "클러스터 구성요소용 네임스페이스입니다" | A namespace beginning with kube- was given | Give the application namespace |
The build continues after leaving with Ctrl+C | This is expected | Ctrl+C only stops the log output. To stop the build, use cancel-build |
bc STATUS is "비교 불가 (빌드 이미지 기록 없음)" | The tag policy is GitRef and the build's pod has been cleaned up, so the address of the created image is unknown | Check deployment on the Console Deployment detail (see 3.2). If you need this every time, switch the tag policy to Unique (see 4.2) |
A build that fails fails for the same reasons whether it was run from a screen or the command line. Look for the symptom in "What to Check When It Fails" in 4.2.
Checking the Result in the Console
Even when building and deploying from the command line, check the result in the Console.
| What to check | Where |
|---|---|
| The build config and its latest build status | Build > Build Configs (see 4.2) |
| Build logs and history | Build > Builds (see 4.3) |
| Whether pods started, and their logs | Workloads > Pods (see 3.1) |
| The deployed image tag | Workloads > Deployment detail (see 3.2) |
| The external access address | Network > Ingresses (see 5.1) |
Confirm on the Deployment detail that the deployed image tag matches the build you just ran.