initial open source

.gitattributes

@@ -0,0 +1,4 @@
+*.star linguist-language=Starlark
+
+# ignore YAML files generated by kubebuilder
+pkg/internal/tests/cluster/crd/** linguist-generated=true

.gitignore

@@ -0,0 +1,36 @@
+
+# Binaries for programs and plugins
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+bin
+testbin/*
+
+# Test binary, docker 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
+*~
+tilt_modules/
+
+*.kubeconfig
+
+# local development tilt settings
+tilt_config.json
+
+# goreleaser
+dist/
+
+# terraform
+.terraform/

CODEOWNERS

@@ -0,0 +1 @@
+* @reddit/achilles

Makefile

@@ -0,0 +1,63 @@
+SHELL:=/bin/bash
+
+PWD := $(PWD)
+CONTROLLER_GEN := $(PWD)/bin/controller-gen
+CONTROLLER_GEN_CMD := $(CONTROLLER_GEN)
+GOSIMPORTS := $(PWD)/bin/gosimports
+GOSIMPORTS_CMD := $(GOSIMPORTS)
+STATICCHECK := $(PWD)/bin/staticcheck
+STATICCHECK_CMD := $(STATICCHECK)
+
+# ENVTEST_K8S_VERSION refers to the version of kubebuilder assets to be downloaded by envtest binary.
+ENVTEST_K8S_VERSION = 1.29
+ENVTEST := $(PWD)/bin/setup-envtest
+ENVTEST_CMD := $(ENVTEST)
+
+# go-get-tool will 'go get' any package $2 and install it to $1.
+PROJECT_DIR := $(shell dirname $(abspath $(lastword $(MAKEFILE_LIST))))
+define go-get-tool
+@[ -f $(1) ] || { \
+set -e ;\
+echo "Downloading $(2)" ;\
+GOBIN=$(PROJECT_DIR)/bin go install -modfile=tools/go.mod $(2) ;\
+}
+endef
+
+.PHONY: test-manifests
+test-manifests: $(CONTROLLER_GEN)
+	$(CONTROLLER_GEN) rbac:roleName=manager-role crd webhook paths="./pkg/internal/tests/api/..." output:crd:artifacts:config=pkg/internal/tests/cluster/crd/bases
+	$(CONTROLLER_GEN) object paths="./pkg/internal/tests/api/..."
+
+.PHONY: generate
+generate: test-manifests $(GOSIMPORTS)
+	go generate ./...
+	$(GOSIMPORTS_CMD) -local github.com/reddit/achilles-sdk -l -w .
+
+KUBEBUILDER_ASSETS = $(shell $(ENVTEST_CMD) --arch=amd64 use $(ENVTEST_K8S_VERSION) -p path)
+.PHONY: test
+test: $(ENVTEST) test-manifests
+	KUBEBUILDER_ASSETS="$(KUBEBUILDER_ASSETS)" go test -race ./...
+
+.PHONY: lint
+lint: $(STATICCHECK) $(GOSIMPORTS)
+	cd tools && go mod tidy
+	go mod tidy
+	go fmt ./...
+	go list ./... | grep -v encoding/json | xargs go vet # ignore forked encoding/json pkg
+	go list ./... | grep -v encoding/json | xargs $(STATICCHECK_CMD) # ignore forked encoding/json pkg
+	$(GOSIMPORTS_CMD) -local github.com/reddit/achilles-sdk -l -w .
+
+$(CONTROLLER_GEN):
+	$(call go-get-tool,$(CONTROLLER_GEN),sigs.k8s.io/controller-tools/cmd/controller-gen)
+
+$(KUSTOMIZE):
+	$(call go-get-tool,$(KUSTOMIZE),sigs.k8s.io/kustomize/kustomize/v4)
+
+$(GOSIMPORTS):
+	$(call go-get-tool,$(GOSIMPORTS),github.com/rinchsan/gosimports/cmd/gosimports)
+
+$(STATICCHECK):
+	$(call go-get-tool,$(STATICCHECK),honnef.co/go/tools/cmd/staticcheck)
+
+$(ENVTEST):
+	$(call go-get-tool,$(ENVTEST),sigs.k8s.io/controller-runtime/tools/setup-envtest)

README.md

@@ -0,0 +1,88 @@
+# Achilles SDK
+[![Reticle Badge](https://reticle.snooguts.net/api/reticle_badge?repo_name=reddit/achilles-sdk)](https://reticle.snooguts.net/repos/reddit/achilles-sdk)
+
+> Achilles home: [go/achilles](https://go.snooguts.net/achilles)
+
+The Achilles SDK offers efficient
+[controller](https://kubernetes.io/docs/concepts/architecture/controller/) and
+[operator](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/)
+creation by allowing engineers to focus on defining their automation business logic, modeled as transitions between resources states (i.e. an FSM). This
+significantly lessens the knowledge of controller and Kubernetes plumbing
+typically required to build controllers. It also forces standardization to
+ensure consistency amongst controllers at Reddit, providing common functionality
+such as metrics, logging, reusable API structs, etc..
+
+As an example, assume you wanted to create a declarative API that allows
+developers to request object storage for their application. The API you wish to
+expose may look something like:
+
+```yaml
+apiVersion: infra.snooguts.net/v1alpha1
+kind: ObjectStorage
+metadata:
+  name: persistent-storage
+  namespace: web-apps
+spec:
+  encrypted: true
+  region: us-east
+  versioning: true
+```
+
+To define this API, you'll use a common-convention with Go structs to
+automatically generate the
+[CustomResourceDefinition](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/#:~:text=The%20CustomResourceDefinition%20API%20resource%20allows,storage%20of%20your%20custom%20resource.)
+(API). Then you'll define the states and transition logic, such as:
+
+![FSM Flow](docs/imgs/fsm-flow.png)
+
+Along with doing the underlying plumbing to support this controller,
+achilles-sdk is providing you logging, metrics, rate-limiting, and
+more.
+
+Lastly, in modeling your controller logic this way, you end up with a clean
+directed graph that models a
+[finite-state-machine](https://en.wikipedia.org/wiki/Finite-state_machine)
+(FSM). This can significantly reduce the cognitive overhead of reasoning about
+what a controller is doing or the state an object is in. More on FSM in the
+documentation.
+
+## Documentation
+
+* [Creating a controller](https://pages.github.snooguts.net/reddit/achilles-docs/dev/sdk/tutorial/)
+    * Comprehensive guide on the implementation of a controller with
+      achilles-sdk.
+* [Reconciler (FSM) Framework](docs/README.md)
+    * Overview of how achilles-sdk works by offering a finite-state machine
+      orchestrated with a Kubernetes reconciler.
+
+## How to Contribute
+1. Clone the repo locally.
+2. Create a new branch
+  - Make sure the branch is pushed to this repo, rather than from a fork. This allows us to easily test the branch code in our Tilt environment.
+3. Make changes and test.
+4. Submit a Pull Request with an appropriate description.
+5. Merge PR once it is approved.
+
+## Releasing
+After incorporating your changes into the achilles-sdk repository, you can publish a new release to make the updated functionality available for repos that consume achilles-sdk such as [achilles](https://github.snooguts.net/reddit/achilles).
+
+#### Publish a new release:
+1. Navigate to the [GHE releases page for achilles-sdk](https://github.com/reddit/achilles-sdk/releases) and click the “Draft a new release” button in the top right
+2. Choose the appropriate next semantic version (`major.minor.patch`):
+   - If there are breaking code changes (e.g., new function signatures for public functions), increment the minor version if the release is pre-1.0, otherwise increment the major version
+   - If there are no breaking changes, increment the patch version if pre-1.0, otherwise increment the minor version if adding functionality or the patch version if fixing bugs
+   - To create a tag with the new version, click the “Choose a tag” button. Enter the new version number and click “Create new tag: `$your-tagname-here` on publish.”
+3. Click the “Generate release notes” button and verify that the changes align with expectations. If everything looks good, publish the release
+
+#### Make updated functionality available for repos like achilles:
+1. Create a branch in the achilles repository
+2. Run the following command to upgrade the achilles-sdk version (replace v0.7.1 with the new version number):  
+   `go get github.com/reddit/[email protected]`
+3. Run a `git diff` and validate that the changes made to `go.mod` and `go.sum` are as expected. The diff should look something like the changes in this [PR](https://github.snooguts.net/reddit/achilles/pull/1135/files).
+4. Create a PR in the achilles repo with the newly upgraded achilles-sdk version
+
+<b>Note:</b> There are several other repos that also consume achilles-sdk but the current pattern is to allow consumers to update at their own leisure. The main repo that should for sure be updated to adopt the latest features is `reddit/achilles`.
+
+## Questions
+
+If you have any questions, please reach out to the `#achilles` Slack channel.

docs/README.md

@@ -0,0 +1,3 @@
+# FSM Reconciler Framework
+
+This guide has moved to the [Achilles docs website](https://pages.github.snooguts.net/reddit/achilles-docs/dev-guides/sdk-apply-objects/).

docs/developer/updating_resources.md

@@ -0,0 +1,3 @@
+# Updating Resources
+
+This guide has moved to the [Achilles docs website](https://pages.github.snooguts.net/reddit/achilles-docs/dev-guides/sdk-apply-objects/).

docs/guide.md

@@ -0,0 +1,3 @@
+# Creating a Controller
+
+This guide has moved to the [Achilles docs website](https://pages.github.snooguts.net/reddit/achilles-docs/dev/sdk/tutorial/).

docs/operator/labels.md

@@ -0,0 +1,3 @@
+# Labels
+
+This guide has moved to the [Achilles docs website](https://pages.github.snooguts.net/reddit/achilles-docs/runbooks/labels/).

go.mod

@@ -0,0 +1,83 @@
+module github.com/reddit/achilles-sdk
+
+go 1.22.5
+
+toolchain go1.22.7
+
+require (
+	github.com/fgrosse/zaptest v1.1.0
+	github.com/go-logr/zapr v1.3.0
+	github.com/gobuffalo/flect v0.3.0
+	github.com/google/go-cmp v0.6.0
+	github.com/iancoleman/strcase v0.2.0
+	github.com/onsi/ginkgo/v2 v2.17.1
+	github.com/onsi/gomega v1.32.0
+	github.com/prometheus/client_golang v1.19.0
+	github.com/prometheus/client_model v0.6.0
+	github.com/reddit/achilles-sdk-api v0.0.0-20241029144808-3486513ce3c7
+	github.com/spf13/pflag v1.0.6-0.20210604193023-d5e0c0615ace
+	github.com/stretchr/testify v1.9.0
+	go.uber.org/zap v1.27.0
+	golang.org/x/exp v0.0.0-20240222234643-814bf88cf225
+	golang.org/x/sync v0.7.0
+	golang.org/x/time v0.5.0
+	golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d
+	k8s.io/api v0.29.3
+	k8s.io/apiextensions-apiserver v0.29.3
+	k8s.io/apimachinery v0.30.0
+	k8s.io/client-go v0.29.3
+	k8s.io/utils v0.0.0-20231127182322-b307cd553661
+	sigs.k8s.io/controller-runtime v0.17.3
+	sigs.k8s.io/yaml v1.4.0
+)
+
+require (
+	github.com/beorn7/perks v1.0.1 // indirect
+	github.com/cespare/xxhash/v2 v2.2.0 // indirect
+	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
+	github.com/emicklei/go-restful/v3 v3.11.0 // indirect
+	github.com/evanphx/json-patch v5.7.0+incompatible // indirect
+	github.com/evanphx/json-patch/v5 v5.9.0 // indirect
+	github.com/fsnotify/fsnotify v1.7.0 // indirect
+	github.com/go-logr/logr v1.4.2 // indirect
+	github.com/go-openapi/jsonpointer v0.21.0 // indirect
+	github.com/go-openapi/jsonreference v0.21.0 // indirect
+	github.com/go-openapi/swag v0.23.0 // indirect
+	github.com/go-task/slim-sprig v0.0.0-20230315185526-52ccab3ef572 // indirect
+	github.com/gogo/protobuf v1.3.2 // indirect
+	github.com/golang/groupcache v0.0.0-20210331224755-41bb18bfe9da // indirect
+	github.com/golang/protobuf v1.5.4 // indirect
+	github.com/google/gnostic-models v0.6.8 // indirect
+	github.com/google/gofuzz v1.2.0 // indirect
+	github.com/google/pprof v0.0.0-20240117000934-35fc243c5815 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/imdario/mergo v0.3.16 // indirect
+	github.com/josharian/intern v1.0.0 // indirect
+	github.com/json-iterator/go v1.1.12 // indirect
+	github.com/mailru/easyjson v0.7.7 // indirect
+	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
+	github.com/modern-go/reflect2 v1.0.2 // indirect
+	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
+	github.com/onsi/ginkgo v1.16.5 // indirect
+	github.com/pkg/errors v0.9.1 // indirect
+	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
+	github.com/prometheus/common v0.49.0 // indirect
+	github.com/prometheus/procfs v0.12.0 // indirect
+	go.uber.org/multierr v1.11.0 // indirect
+	golang.org/x/mod v0.17.0 // indirect
+	golang.org/x/net v0.27.0 // indirect
+	golang.org/x/oauth2 v0.21.0 // indirect
+	golang.org/x/sys v0.22.0 // indirect
+	golang.org/x/term v0.22.0 // indirect
+	golang.org/x/text v0.16.0 // indirect
+	gomodules.xyz/jsonpatch/v2 v2.4.0 // indirect
+	google.golang.org/protobuf v1.34.1 // indirect
+	gopkg.in/inf.v0 v0.9.1 // indirect
+	gopkg.in/yaml.v2 v2.4.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+	k8s.io/component-base v0.29.3 // indirect
+	k8s.io/klog/v2 v2.120.1 // indirect
+	k8s.io/kube-openapi v0.0.0-20240228011516-70dd3763d340 // indirect
+	sigs.k8s.io/json v0.0.0-20221116044647-bc3834ca7abd // indirect
+	sigs.k8s.io/structured-merge-diff/v4 v4.4.1 // indirect
+)