Merge pull request #1 from oracle-devrel/feature-init

Initial commit

Author: martatolosa

.gitignore

@@ -1,3 +1,30 @@
+# Created by https://www.toptal.com/developers/gitignore/api/macos,go,visualstudiocode
+# Edit at https://www.toptal.com/developers/gitignore?templates=macos,go,visualstudiocode
+
+### Go ###
+# If you prefer the allow list template instead of the deny list, see community template:
+# https://github.com/github/gitignore/blob/main/community/Golang/Go.AllowList.gitignore
+#
+# Binaries for programs and plugins
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Test binary, built with `go test -c`
+*.test
+
+# Output of the go coverage tool, specifically when used with LiteIDE
+*.out
+
+# Dependency directories (remove the comment below to include it)
+# vendor/
+
+# Go workspace file
+go.work
+
+### macOS ###
 # General
 .DS_Store
 .AppleDouble
@@ -26,8 +53,27 @@ Network Trash Folder
 Temporary Items
 .apdisk
 
-# ignore common security keys
-.key
-.crt
-.csr
-.pem
+### macOS Patch ###
+# iCloud generated files
+*.icloud
+
+### VisualStudioCode ###
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+!.vscode/*.code-snippets
+
+# Local History for Visual Studio Code
+.history/
+
+# Built Visual Studio Code Extensions
+*.vsix
+
+### VisualStudioCode Patch ###
+# Ignore all local history of files
+.history
+.ionide
+
+# End of https://www.toptal.com/developers/gitignore/api/macos,go,visualstudiocode

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2021 Oracle and/or its affiliates.
+Copyright (c) 2024 Oracle and/or its affiliates.
 
 The Universal Permissive License (UPL), Version 1.0
 
@@ -32,4 +32,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

README.md

@@ -1,32 +1,44 @@
-# oke-credential-provider-for-ocir
+# Image Credential Provider for OKE
 
-[![License: UPL](https://img.shields.io/badge/license-UPL-green)](https://img.shields.io/badge/license-UPL-green) [![Quality gate](https://sonarcloud.io/api/project_badges/quality_gate?project=oracle-devrel_oke-credential-provider-for-ocir)](https://sonarcloud.io/dashboard?id=oracle-devrel_oke-credential-provider-for-ocir)
+<b>Image Credential Provider</b> (Provider) for  [Container Engine for Kubernetes (OKE)](https://www.oracle.com/cloud/cloud-native/container-engine-kubernetes/) is the implementation of [Kubelet CredentialProvider (v1) APIs](https://kubernetes.io/docs/reference/config-api/kubelet-credentialprovider.v1/) for passwordless pulls from the [Container Registry (OCIR)](https://www.oracle.com/cloud/cloud-native/container-registry/) (OCIR). It's useful since OKE typically [requires](https://docs.oracle.com/en-us/iaas/Content/ContEng/Tasks/contengpullingimagesfromocir.htm) a stored Secret to pull private OCIR images, referenced with `imagePullSecrets` in a manifest. With the provider in place, Kubelet will pull images using instance principal authentication, giving you a seamless image-pulling experience without hosting static Docker credentials.
 
-## THIS IS A NEW, BLANK REPO THAT IS NOT READY FOR USE YET.  PLEASE CHECK BACK SOON!
+## Table of Contents
+- [Prerequisites](#prerequisites)
+- [Installation](#installation)
+- [Contributing](#contributing)
+- [License](#license)
 
-## Introduction
-MISSING
+## Prerequisites 
+Your OKE Kubelet and API Server versions must be at least v1.26. To check the version, execute `kubectl version`.
 
-## Getting Started
-MISSING
 
-### Prerequisites
-MISSING
+## Installation
+To install and run the Provider on a worker nodes, follow the steps described [here](/examples/run-on-worker-instance-principal/). 
 
-## Notes/Issues
-MISSING
+It's crucial to (1) [create](#1-create-dynamic-group-for-oke-worker-nodes) a dynamic group to represent worker nodes, (2) [create](#2-create-policy-to-pull-images) a Policy to authorize pulling from OCIR, and (3) [configure](#3-configure-cloud-init-for-oke-node-pool) a cloud-init script to do the heavy lifting.
 
-## URLs
-* Nothing at this time
+## How the Provider Works
+The plugin implementation leverages the Kubelet capability introduced in v1.26. Kubelet uses [CredentialProvider](https://kubernetes.io/docs/reference/config-api/kubelet-credentialprovider.v1/) APIs to fetch authentication credentials against Docker comaptible image registry and caches it on the worker node level. The plugin translates instance principal authentication into the JWT token that is used by Kubelet when pulling images from OCIR at runtime. In that case, you don't need to specify `imagePullSecrets` in a manifest, since Kubelet has JWT token based on instance principal auth locally.
+
+The provider is injected into Kubelet via the extra `kubelet-extra-args`:
+- `--image-credential-provider-config` sets the path to the Image Credential Provider for OKE config file.
+- `--image-credential-provider-bin-dir` sets the path to the directory where the Image Credential Provider for OKE binary is located.
+
+The cloud-init script act as glue, downloading the provider with the configuration file and passing it to the Kubelet. 
+
+The current [cloud-init.sh](examples/run-on-worker-instance-principal/cloud-init.sh) example implementation uses the `wget` utility to download binaries on the worker nodes. Suppose you don't have access to the Internet (through NAT gateway) or your OS does not have a `wget`. In that case, you need to place binaries and configuration in the appropriate folders manually:
+- The [provider binary (amd64)](https://github.com/oracle-devrel/oke-credential-provider-for-ocir/releases/latest/download/oke-credential-provider-for-ocir-linux-amd64) with the name `oke-credential-provider` must be in the following path: `/usr/local/bin`. Make sure the binary has permission mode to execute. You can enable it by executing `sudo chmod 755 /usr/local/bin/oke-credential-provider`.
+- The kubelet configuration file [credential-provider-config.yaml](https://github.com/oracle-devrel/oke-credential-provider-for-ocir/releases/latest/download/credential-provider-config.yaml) must be placed in the path `/etc/kubernetes`.
+
+Plugin binaries are avaialble both for OCI [arm64](https://github.com/oracle-devrel/oke-credential-provider-for-ocir/releases/latest/download/oke-credential-provider-for-ocir-linux-arm64) and [amd64](https://github.com/oracle-devrel/oke-credential-provider-for-ocir/releases/latest/download/oke-credential-provider-for-ocir-linux-amd64) architectures.
 
 ## Contributing
-This project is open source.  Please submit your contributions by forking this repository and submitting a pull request!  Oracle appreciates any contributions that are made by the open source community.
+
+If you find a bug or want to suggest an enhancement, please raise the Issue.
 
 ## License
-Copyright (c) 2022 Oracle and/or its affiliates.
+Copyright (c) 2024 Oracle and/or its affiliates.
 
 Licensed under the Universal Permissive License (UPL), Version 1.0.
 
-See [LICENSE](LICENSE) for more details.
-
-ORACLE AND ITS AFFILIATES DO NOT PROVIDE ANY WARRANTY WHATSOEVER, EXPRESS OR IMPLIED, FOR ANY SOFTWARE, MATERIAL OR CONTENT OF ANY KIND CONTAINED OR PRODUCED WITHIN THIS REPOSITORY, AND IN PARTICULAR SPECIFICALLY DISCLAIM ANY AND ALL IMPLIED WARRANTIES OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY, AND FITNESS FOR A PARTICULAR PURPOSE.  FURTHERMORE, ORACLE AND ITS AFFILIATES DO NOT REPRESENT THAT ANY CUSTOMARY SECURITY REVIEW HAS BEEN PERFORMED WITH RESPECT TO ANY SOFTWARE, MATERIAL OR CONTENT CONTAINED OR PRODUCED WITHIN THIS REPOSITORY. IN ADDITION, AND WITHOUT LIMITING THE FOREGOING, THIRD PARTIES MAY HAVE POSTED SOFTWARE, MATERIAL OR CONTENT TO THIS REPOSITORY WITHOUT ANY REVIEW. USE AT YOUR OWN RISK. 
+See [LICENSE](LICENSE) for more details.

cmd/provider.go

@@ -0,0 +1,21 @@
+/*
+ * Copyright (c) 2024 Oracle and/or its affiliates.
+ * Use of this source code is governed by The Universal Permissive License (UPL), Version 1.0. that can be found in the LICENSE file.
+ */
+
+package main
+
+import (
+	"flag"
+
+	"github.com/devrocks/credential-provider-oke/internal/helpers"
+	"github.com/devrocks/credential-provider-oke/internal/provider"
+)
+
+func main() {
+	var configType string
+	flag.StringVar(&configType, "config", "", "Type the absolute path to yaml file with provider configuration. If it's ommited, program reads from environment variables (REGISTRY_TOKEN_PATH, DEFAULT_USER, REGISTRY_PROTOCOL, OCIR_AUTH_METHOD).")
+	flag.Parse()
+	config := helpers.ReadConfig(configType)
+	provider.GetCredentialProviderResponse(config)
+}

examples/run-locally-yaml/README.md

@@ -0,0 +1,20 @@
+# Running the Provider Locally
+
+You can use the following steps to run the provider locally and test the functionality. The script assumes you have OCI CLI installed and configured.
+
+Execute the following command:
+```
+echo '{
+  "apiVersion": "credentialprovider.kubelet.k8s.io/v1",
+  "kind": "CredentialProviderRequest",
+  "image": "fra.ocir.io/demo_namespace/demo_repo/demo_image"
+}' | go run cmd/provider.go -config ./examples/run-locally-yaml/config.yaml
+```
+
+If you have OCI CLI installed and configured properly, you should see the output below:
+```
+{"apiVersion":"credentialprovider.kubelet.k8s.io/v1","kind":"CredentialProviderResponse","cacheKeyType":"Registry","cacheDuration":"0h59m0s","auth":{"fra.ocir.io":{"username":"","password":""}}}
+```
+
+That's it!
+

examples/run-locally-yaml/config.yaml

@@ -0,0 +1,4 @@
+registryTokenPath: /20180419/docker/token
+defaultUser: BEARER_TOKEN
+registryProtocol: https
+ocirAuthMethod: USER_PRINCIPAL

examples/run-on-worker-instance-principal/README.md

@@ -0,0 +1,22 @@
+# Running the Provider on a Worker Node
+
+To run the Provider on a worker node, follow the steps below. It's crucial to (1) [create](#1-create-dynamic-group-for-oke-worker-nodes) a dynamic group to represent worker nodes, (2) [create](#2-create-policy-to-pull-images) a Policy to authorize pulling from OCIR, and (3) [configure](#3-configure-cloud-init-for-oke-node-pool) a cloud-init script to do the heavy lifting.
+
+## 1. Create Dynamic Group for OKE Worker Nodes
+First, you must [create a dynamic group](https://docs.oracle.com/en-us/iaas/Content/Identity/dynamicgroups/To_create_a_dynamic_group.htm) representing worker nodes of a targeted OKE cluster. The example below adds all instances within the compartment to the dynamic group `oke-puller`.
+```
+All {instance.compartment.id = '<REPLACE_WITH_YOUR_COMPARTMENT_OCID>'}
+```
+Replace `<REPLACE_WITH_YOUR_COMPARTMENT_OCID>` with the actual compartment OCID where the worker nodes reside. Make sure that targeted worker nodes are a part of the compartment.
+
+Additionally, you might expand the dynamic group expression to defined tags for better precision in selecting worker nodes.
+
+## 2. Create Policy to Pull Images
+[Create the policy](https://docs.oracle.com/en-us/iaas/Content/Identity/policymgmt/managingpolicies_topic-To_create_a_policy.htm) to authorize dynamic group `oke-puller` to pull images from OCIR. The example below allows the dynamic group `oke-puller` to pull images from any repository in a selected compartment.
+```
+Allow dynamic-group <REPLACE_WITH_YOUR_IAM_DOMAIN>/oke-puller to read repos in compartment <REPLACE_WITH_YOUR_COMPARTMENT_NAME>
+```
+Replace `<REPLACE_WITH_YOUR_IAM_DOMAIN>` with the IAM domain name. Replace `<REPLACE_WITH_YOUR_COMPARTMENT_NAME>` with the compartment name of the repositories with images.
+
+## 3. Configure Cloud-Init for OKE Node Pool
+The plugin is activated with the cloud-init executed at the boot time of every worker node. OKE uses cloud-init to set up the compute instances hosting managed nodes. Paste the [following](cloud-init.sh) cloud-init script to every node pool where you want to enable Image Credential Provider for OKE. Node pools must be a part of the dynamic group `oke-puller`.

examples/run-on-worker-instance-principal/cloud-init.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+curl --fail -H "Authorization: Bearer Oracle" -L0 http://169.254.169.254/opc/v2/instance/metadata/oke_init_script | base64 --decode >/var/run/oke-init.sh
+
+# download binaries on the worker node
+wget https://github.com/oracle-devrel/oke-credential-provider-for-ocir/releases/latest/download/oke-credential-provider-for-ocir-linux-amd64 -O /usr/local/bin/credential-provider-oke
+wget https://github.com/oracle-devrel/oke-credential-provider-for-ocir/releases/latest/download/credential-provider-config.yaml -P /etc/kubernetes/
+
+# add permission to execute
+sudo chmod 755 /usr/local/bin/credential-provider-oke
+
+# configure kubelet with image credential provider
+bash /var/run/oke-init.sh --kubelet-extra-args "--image-credential-provider-bin-dir=/usr/local/bin/ --image-credential-provider-config=/etc/kubernetes/credential-provider-config.yaml"

examples/run-on-worker-instance-principal/credential-provider-config.yaml

@@ -0,0 +1,18 @@
+apiVersion: kubelet.config.k8s.io/v1
+kind: CredentialProviderConfig
+providers:
+- name: credential-provider-oke
+  apiVersion: credentialprovider.kubelet.k8s.io/v1
+  matchImages:
+  - "*.ocir.io"
+  defaultCacheDuration: 55m
+  env:
+  - name: REGISTRY_TOKEN_PATH
+    value: /20180419/docker/token
+  - name: DEFAULT_USER
+    value: BEARER_TOKEN
+  - name: REGISTRY_PROTOCOL
+    value: https
+  - name: OCIR_AUTH_METHOD
+    value: INSTANCE_PRINCIPAL
+    

go.mod

@@ -0,0 +1,8 @@
+module github.com/devrocks/credential-provider-oke
+
+go 1.21.7
+
+require (
+	github.com/oracle/oci-go-sdk v24.3.0+incompatible // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)