Implement ExecutionHook CRDs API Types

.gitignore

@@ -0,0 +1,24 @@
+
+# Binaries for programs and plugins
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+bin
+
+# Test binary, build with `go test -c`
+*.test
+
+# Output of the go coverage tool, specifically when used with LiteIDE
+*.out
+
+# Kubernetes Generated files - skip generated files, except for vendored files
+
+!vendor/**/zz_generated.*
+
+# editor and IDE paraphernalia
+.idea
+*.swp
+*.swo
+*~

Dockerfile

@@ -0,0 +1,26 @@
+# Build the manager binary
+FROM golang:1.13 as builder
+
+WORKDIR /workspace
+# Copy the Go Modules manifests
+COPY go.mod go.mod
+COPY go.sum go.sum
+# cache deps before building and copying source so that we don't need to re-download as much
+# and so that source changes don't invalidate our downloaded layer
+RUN go mod download
+
+# Copy the go source
+COPY main.go main.go
+COPY ./ ./
+
+# Build
+RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 GO111MODULE=on go build -a -o manager main.go
+
+# Use distroless as minimal base image to package the manager binary
+# Refer to https://github.com/GoogleContainerTools/distroless for more details
+FROM gcr.io/distroless/static:nonroot
+WORKDIR /
+COPY --from=builder /workspace/manager .
+USER nonroot:nonroot
+
+ENTRYPOINT ["/manager"]

Makefile

@@ -0,0 +1,111 @@
+# Copyright 2020 The Kubernetes Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+.DEFAULT_GOAL:=help
+
+REGISTRY ?= gcr.io/$(shell gcloud config get-value project)
+IMAGE_NAME ?= executionhook-controller
+TAG ?= dev
+# Image URL to use all building/pushing image targets
+CONTROLLER_IMAGE ?= $(REGISTRY)/$(IMAGE_NAME):$(TAG)
+# Produce CRDs that work back to Kubernetes 1.11 (no version conversion)
+CRD_OPTIONS ?= "crd:trivialVersions=true"
+
+# Directories.
+TOOLS_DIR := hack/tools
+TOOLS_BIN_DIR := $(TOOLS_DIR)/bin
+
+# Tool binaries.
+KUSTOMIZE := $(TOOLS_BIN_DIR)/kustomize
+CONTROLLER_GEN := $(TOOLS_BIN_DIR)/controller-gen
+
+$(CONTROLLER_GEN): $(TOOLS_DIR)/go.mod
+	cd $(TOOLS_DIR); go build -tags=tools -o ./bin/controller-gen sigs.k8s.io/controller-tools/cmd/controller-gen
+
+$(KUSTOMIZE): $(TOOLS_DIR)/go.mod
+	cd $(TOOLS_DIR); go build -tags=tools -o ./bin/kustomize sigs.k8s.io/kustomize/kustomize/v3
+
+.PHONY: help
+help:  ## Display this help
+	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z_-]+:.*?##/ { printf "  \033[36m%-15s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)
+
+.PHONY: clean-bin
+clean-bin: ## Remove all generated binaries
+	rm -rf bin
+	rm -rf hack/tools/bin
+
+.PHONY: all
+all: manager
+
+.PHONY: test
+test: generate fmt vet manifests ## Run tests
+	go test -v ./... -coverprofile cover.out
+
+.PHONY: manager
+manager: generate fmt vet test ## Build manager binary
+	go build -o bin/manager main.go
+
+.PHONY: install
+install: manifests $(KUSTOMIZE) ## Install CRDs into a cluster in the current context at ~/.kube/config
+	$(KUSTOMIZE) build config/crd | kubectl apply -f -
+
+.PHONY: uninstall
+uninstall: manifests $(KUSTOMIZE) ## Uninstall latest version of CRDs from a cluster in the current context at ~/.kube/config
+	$(KUSTOMIZE) build config/crd | kubectl delete -f -
+
+.PHONY: deploy
+# hacky, works for now. TODO: ashish-amarnath make this better
+deploy: manifests $(KUSTOMIZE) ## Deploy controller in the configured Kubernetes cluster in ~/.kube/config
+	cd config/manager && ../../$(KUSTOMIZE) edit set image controller=${CONTROLLER_IMAGE}
+	$(KUSTOMIZE) build config/default | kubectl apply -f -
+
+.PHONY: manifests
+manifests: $(CONTROLLER_GEN) ## Generate manifests e.g. CRD, RBAC etc.
+	$(CONTROLLER_GEN) $(CRD_OPTIONS) rbac:roleName=manager-role webhook paths="./..." output:crd:artifacts:config=config/crd/bases
+
+fmt: ## Run go fmt against code
+	go fmt ./...
+
+vet: ## Run go vet against code
+	go vet ./...
+
+.PHONY: modules
+modules: ## Runs go mod to ensure modules are up-to-date.
+	go mod tidy
+	cd $(TOOLS_DIR); go mod tidy
+
+.PHONY: verify-modules
+verify-modules: modules
+	@if !(git diff --quiet HEAD -- go.sum go.mod hack/tools/go.mod hack/tools/go.sum); then \
+		echo "go module files are out of date"; exit 1; \
+	fi
+
+generate: $(CONTROLLER_GEN) ## Generate code
+	$(CONTROLLER_GEN) object:headerFile=./hack/boilerplate.go.txt paths="./..."
+
+
+.PHONY: verify-gen
+verify-gen: generate manifests
+	@if !(git diff --quiet HEAD); then \
+		echo "generated code and manifest files are out of date, run make generate manifests"; exit 1; \
+	fi
+
+.PHONY: docker-build
+docker-build: test # Build the controller image
+	docker build . -t ${CONTROLLER_IMAGE}
+
+.PHONY: docker-push
+docker-push: docker-build # Push the controller image
+	docker push ${CONTROLLER_IMAGE}
+

PROJECT

@@ -0,0 +1,10 @@
+domain: k8s.io
+repo: sigs.k8s.io/execution-hook
+resources:
+- group: apps
+  kind: ExecutionHook
+  version: v1alpha1
+- group: apps
+  kind: HookAction
+  version: v1alpha1
+version: "2"

README.md

@@ -3,6 +3,11 @@
 This repo contains `ExecutionHook` CRDs for dynamically executing user’s commands in pods/containers
 and an `ExecutionHookController` to manage the hook's lifecycle.
 
+## Usage
+
+Execution Hook uses the [Kubebuilder framework](https://github.com/kubernetes-sigs/kubebuilder).
+See the [Kubebuilder documentation](https://book.kubebuilder.io/introduction.html) for building, running and testing the project.
+
 ## Community, discussion, contribution, and support
 
 Learn how to engage with the Kubernetes community on the [community page](http://kubernetes.io/community/).

api/v1alpha1/executionhook_types.go

@@ -0,0 +1,189 @@
+/*
+Copyright 2020 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package v1alpha1
+
+import (
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
+
+const (
+	// ExecutionHookFinalizer allows ExecutionHook controller to clean up the custom resource before
+	// removing it from the apiserver.
+	ExecutionHookFinalizer = "executionhook.apps.x-k8s.io"
+)
+
+// +kubebuilder:object:root=true
+// +kubebuilder:resource:path=executionhook,shortName=eh,scope=Namespaced,categories=executionhook
+// +kubebuilder:subresource:status
+
+// ExecutionHook is the Schema for the executionhook API
+type ExecutionHook struct {
+	metav1.TypeMeta `json:",inline"`
+	// Metadata associated with persisted resources
+	metav1.ObjectMeta `json:"metadata,omitempty"`
+
+	// ExecutionHookSpec defines the desired state of ExecutionHook
+	Spec ExecutionHookSpec `json:"spec,omitempty"`
+	// ExecutionHookStatus defines the observed state of ExecutionHook
+	// +optional
+	Status *ExecutionHookStatus `json:"status,omitempty"`
+}
+
+// +kubebuilder:object:root=true
+
+// ExecutionHookList contains a list of ExecutionHook
+type ExecutionHookList struct {
+	metav1.TypeMeta `json:",inline"`
+	metav1.ListMeta `json:"metadata,omitempty"`
+	Items           []ExecutionHook `json:"items"`
+}
+
+// ExecutionHookSpec defines the desired state of ExecutionHook
+// HookActionName is copied to ExecutionHookSpec by the controller such as
+// the Application Snapshot Controller.
+type ExecutionHookSpec struct {
+	// INSERT ADDITIONAL SPEC FIELDS - desired state of cluster
+	// Important: Run "make" to regenerate code after modifying this file
+
+	// PodSelection defines how to select pods and containers to run
+	// the executionhook. If multiple pod/containers are selected, the action will executed on them
+	// asynchronously. If execution ordering is required, caller has to implement the logic and create
+	// different hooks in order.
+	// This field is required.
+	PodSelection PodSelection `json:"podSelection"`
+
+	// Name of the HookAction. This is required.
+	ActionName string `json:"actionName"`
+}
+
+// PodSelection contains two fields, PodContainerNamesList and PodContainerSelector,
+// where exactly one of them must be defined so that the hook controller knows where to
+// run the hook.
+// TODO: Add validation to ensure exactly one of them are defined.
+type PodSelection struct {
+	// PodContainerNamesList lists the pods/containers on which the ExecutionHook
+	// should be executed. If not specified, the ExecutionHook controller will find
+	// all pods and containers based on PodContainerSelector.
+	// If both PodContainerNamesList and PodContainerSelector are not
+	// specified, the ExecutionHook cannot be executed and it will fail.
+	// +optional
+	PodContainerNamesList []PodContainerNames `json:"podContainerNamesList,omitempty"`
+
+	// PodContainerSelector is for hook controller to find pods and containers
+	// based on the pod label selector and container names
+	// If PodContainerNamesList is specified, this field will not be used.
+	// +optional
+	PodContainerSelector *PodContainerSelector `json:"podContainerSelector,omitempty"`
+}
+
+// PodContainerNames lists the containers the ExecutionHook should be executed on in a Pod.
+type PodContainerNames struct {
+	// This field is required
+	PodName string `json:"podName"`
+
+	// +optional
+	// If empty, hook action will be executed on all containers in the pod.
+	ContainerNames []string `json:"containerNames,omitempty"`
+}
+
+// PodContainerSelector defines the selector and containers the ExecutionHook
+// should be executed on.
+type PodContainerSelector struct {
+	// PodSelector specifies a label query over a set of pods.
+	// If not specified, all pods in the namespace will be slected to look for containers
+	// specified in the ContainerList.
+	// +optional
+	PodSelector *metav1.LabelSelector `json:"podSelector,omitempty"`
+
+	// If specified, controller will only select these containers from the selected pods based on PodSelector.
+	// Otherwise, all containers of the selected pods will be chosen for hook execution.
+	// +optional
+	ContainerList []string `json:"containerList,omitempty"`
+}
+
+// ExecutionHookStatus defines the observed state of ExecutionHook
+type ExecutionHookStatus struct {
+	// INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
+	// Important: Run "make" to regenerate code after modifying this file
+
+	// This is a list of ContainerExecutionHookStatus, with each status representing
+	// information about how hook is executed in a container, including pod name,
+	// container name, Timestamp, Succeed, etc.
+	// +optional
+	HookStatuses []ContainerExecutionHookStatus `json:"hookStatuses,omitempty"`
+}
+
+// ContainerExecutionHookStatus represents the current state of a hook for a specific
+// container in a pod
+type ContainerExecutionHookStatus struct {
+	// This field is required
+	PodName string `json:"podName"`
+
+	// This field is required
+	ContainerName string `json:"containerName"`
+
+	// If not set, it is nil, indicating Action has not started
+	// If set, it means Action has started at the specified time
+	// +optional
+	Timestamp *metav1.Time `json:"timestamp,omitempty"`
+
+	// Succeed is set to true when the action is executed in the container successfully.
+	// It will be set to false if the action cannot be executed successfully after
+	// ActionTimeoutSeconds passes.
+	// +optional
+	Succeed *bool `json:"succeed,omitempty"`
+
+	// The last error encountered when executing the action. The hook controller might
+	// update this field each time it retries the execution.
+	// +optional
+	Error *HookError `json:"error,omitempty"`
+}
+
+// HookError describes the error occurred from hook execution.
+type HookError struct {
+	// Type of the error
+	// This is required
+	ErrorType ErrorType `json:"errorType"`
+
+	// Error message
+	// +optional
+	Message *string `json:"message,omitempty"`
+
+	// More detailed reason why error happens
+	// +optional
+	Reason *string `json:"reason,omitempty"`
+
+	// It indicates when the error occurred
+	// +optional
+	Timestamp *metav1.Time `json:"timestamp,omitempty"`
+}
+
+// ErrorType defines the type of error occurred from hook execution.
+type ErrorType string
+
+// More error types could be added, e.g., Forbidden, Unauthorized, AlreadyInProgress, etc.
+const (
+	// The execution hook times out
+	Timeout ErrorType = "Timeout"
+
+	// The execution hook fails with an error
+	Error ErrorType = "Error"
+)
+
+func init() {
+	SchemeBuilder.Register(&ExecutionHook{}, &ExecutionHookList{})
+}