Merge pull request #91 from upbound/repo-sync/sa-up/default

🔄 synced file(s) with upbound/sa-up
upbound · Nov 25, 2024 · 7f7a974 · 7f7a974
2 parents 9b3b554 + 57b109d
commit 7f7a974
Show file tree

Hide file tree

Showing 2 changed files with 171 additions and 93 deletions.
diff --git a/.github/renovate.json5 b/.github/renovate.json5
@@ -9,6 +9,20 @@
   "prConcurrentLimit": 5,
   "baseBranches": ["main"],
   "labels": ["automated"],
+  "packageRules": [
+    {
+      "matchFiles": [".github/**"],
+      "groupName": "github-actions dependencies"
+    },
+    {
+      "matchFiles": ["crossplane.yaml"],
+      "groupName": "crossplane dependencies"
+    },
+    {
+      "matchFiles": ["Makefile"],
+      "groupName": "Makefile dependencies"
+    }
+  ],
   "customManagers": [
     {
       "customType": "regex",
@@ -18,25 +32,27 @@
         "UP_VERSION = (?<currentValue>.*?)\\n"
       ],
       "datasourceTemplate": "github-releases",
-      "depNameTemplate": "upbound/up",
-    }, {
+      "depNameTemplate": "upbound/up"
+    },
+    {
       "customType": "regex",
       "description": "Bump uptest version in the Makefile",
       "fileMatch": ["^Makefile$"],
       "matchStrings": [
         "UPTEST_VERSION = (?<currentValue>.*?)\\n"
       ],
       "datasourceTemplate": "github-releases",
-      "depNameTemplate": "upbound/uptest",
-    }, {
+      "depNameTemplate": "upbound/uptest"
+    },
+    {
       "customType": "regex",
       "description": "Bump providers/functions/configurations in crossplane.yaml",
       "fileMatch": ["crossplane.yaml"],
       "matchStrings": [
         "#\\s*renovate:\\s*datasource=(?<datasource>[^\\s]+)\\s+depName=(?<depName>[^\\s]+)\\s*\\n\\s*version:\\s*\"(?<currentValue>[^\"]+)\""
       ],
       "datasourceTemplate": "{{{datasource}}}",
-      "depNameTemplate": "{{{depName}}}",
+      "depNameTemplate": "{{{depName}}}"
     }
-  ],
-}
+  ]
+}
diff --git a/Makefile b/Makefile
@@ -1,55 +1,106 @@
-# Usage
 # ====================================================================================
-# Generic Makefile to be used across repositories building a crossplane configuration
-# package
+# Crossplane Configuration Package Makefile
+# ====================================================================================
+
+# USAGE DOCUMENTATION
+# ====================================================================================
+#
+# This is a generic Makefile to be used across repositories building Crossplane
+# configuration packages. It provides a comprehensive set of targets for development,
+# testing, and deployment.
 #
-# Available targets:
+# PROJECT CONFIGURATION
+# -------------------
+# Create a project.mk file in your repository to configure project-specific settings.
+# Required variables:
+# - PROJECT_NAME: Name of your Crossplane configuration package
 #
+# Example project.mk:
+#   PROJECT_NAME = custom-config
+#   UPTEST_DEFAULT_TIMEOUT = 3600s
+#   UPTEST_SKIP_IMPORT = true
+#
+# PRIMARY TARGETS
+# --------------
+#
+# Development Tools:
+# -----------------
 # - `yamllint`
-#   Runs yamllint for all files in `api`-folder recursively
+#   Runs yamllint recursively on all files in the `api` folder to ensure YAML
+#   quality and consistency
+#
+# - `check-examples`
+#   Validates consistency between example configurations and dependencies:
+#   - Compares Function package versions in examples/ against crossplane.yaml
+#   - Ensures all Function versions in examples match dependency declarations
+#   - Helps prevent version mismatches that could cause deployment issues
+#   Example errors:
+#     - Example using function-foo:v1.2.0 while crossplane.yaml specifies v1.1.0
+#     - Missing Function dependencies in crossplane.yaml that are used in examples
+#   Usage: Run before committing changes to ensure example validity
 #
+# Rendering and Validation:
+# -----------------
 # - `render`
-#   Runs crossplane render to render the output of the composition. Usefule for quick
-#   feedback in order to test templating.
-#   Important note:
-#		Claims need following annotations in order for render to work (adjust the paths
-#		if necessary):
-#			render.crossplane.io/composition-path: apis/pat/composition.yaml
-#			render.crossplane.io/function-path: examples/functions.yaml
-#		This will only populate the cache. Use `render.show` to use the output
+#   Renders the composition output for rapid feedback during template development.
+#   Requirements:
+#   - Claims must have these annotations:
+#       render.crossplane.io/composition-path: apis/pat/composition.yaml
+#       render.crossplane.io/function-path: examples/functions.yaml
+#   Note: This only populates the cache. Use `render.show` to view output.
 #
 # - `render.show`
-#   Outputs the rendered yaml, useful for validating the rendered output manually
-#   or together with 'crossplane validate', e.g.:
-#   	`make render.show | crossplane beta validate crossplane.yaml -`
+#   Displays the rendered YAML output. Useful for:
+#   - Manual validation
+#   - Piping to validation tools, e.g.:
+#     make render.show | crossplane beta validate crossplane.yaml -
 #
+# Testing:
+# -----------------
 # - `render.test`
-#   Executes kcl-unit tests on rendered manifests. Tests live in `test`-folder and
-#   can be written as normal kcl-tests
+#   Executes kcl-unit tests on rendered manifests. Tests should be:
+#   - Located in the `test` folder
+#   - Written as standard kcl-tests
+#   This ensures the rendered output meets expected specifications.
 #
 # - `e2e`
-#   Runs full end-to-end test, including creating cluster, setting up the configuration
-#   and testing if create, import and delete work as expected.
-#   In case the configuration creates resources on a cloud provider, it requires the following
-#   environment variables to be set:
-#   UPTEST_CLOUD_CREDENTIALS, cloud credentials for the provider being tested, e.g.
-#   	- for aws: `export UPTEST_CLOUD_CREDENTIALS=$(cat ~/.aws/credentials)`
-#   	- for gcp: `export UPTEST_CLOUD_CREDENTIALS=$(cat gcp-sa.json)`
-#   	- for azure: `export UPTEST_CLOUD_CREDENTIALS=$(cat azure.json)`
-#
-#	Available options:
-#		UPTEST_SKIP_DELETE (default `false`) skips the deletion of any resources created during the test
-#		UPTEST_SKIP_UPDATE (default `false`) skips testing the update of the claims
-#		UPTEST_SKIP_IMPORT (default `true`) skips testing the import of resources
-#	Example:
-#		`make e2e UPTEST_SKIP_DELETE=true`
-#
-# Language specific options:
-#
-# - `KCL`
-#      KCL_COMPOSITION_PATH can be set to the kcl-file creating composition.yaml. Default: `apis/kcl/generate.k`
-
-# Project Setup
+#   Comprehensive end-to-end testing, including:
+#   - Cluster creation
+#   - Configuration setup
+#   - Testing create, import, and delete operations
+#
+#   Cloud Provider Requirements:
+#   For configurations creating cloud provider resources, set:
+#   UPTEST_CLOUD_CREDENTIALS - Provider-specific credentials:
+#   - AWS:   export UPTEST_CLOUD_CREDENTIALS=$(cat ~/.aws/credentials)
+#   - GCP:   export UPTEST_CLOUD_CREDENTIALS=$(cat gcp-sa.json)
+#   - Azure: export UPTEST_CLOUD_CREDENTIALS=$(cat azure.json)
+#
+#   Configuration Options:
+#   - UPTEST_SKIP_DELETE (default: false)
+#     Skip deletion testing of created resources
+#   - UPTEST_SKIP_UPDATE (default: false)
+#     Skip testing of claim updates
+#   - UPTEST_SKIP_IMPORT (default: false)
+#     Skip testing of resource imports
+#
+#   Example Usage:
+#     make e2e UPTEST_SKIP_DELETE=true
+#
+# LANGUAGE-SPECIFIC OPTIONS
+# ------------------------
+#
+# KCL Support:
+# - KCL_COMPOSITION_PATH
+#   Path to the KCL file generating composition.yaml
+#   Default: apis/kcl/generate.k
+#
+# NOTE: The platform setting is constrained to linux_amd64 as Configuration package
+# images are not architecture-specific. This avoids unnecessary multi-arch image
+# generation.
+
+# ====================================================================================
+# Project Configuration
 # ====================================================================================
 
 # Include project.mk for project specific settings
@@ -59,100 +110,105 @@ ifndef PROJECT_NAME
   $(error PROJECT_NAME is not set. Please create `project.mk` and set it there.)
 endif
 
+# Project Configuration
+# ------------------
 PROJECT_REPO := github.com/upbound/$(PROJECT_NAME)
-
-# NOTE(hasheddan): the platform is insignificant here as Configuration package
-# images are not architecture-specific. We constrain to one platform to avoid
-# needlessly pushing a multi-arch image.
 PLATFORMS ?= linux_amd64
--include build/makelib/common.mk
-
-# ====================================================================================
-# Setup Kubernetes tools
 
+# Tool Versions
+# ------------------
 UP_VERSION = v0.34.0
 UP_CHANNEL = stable
 CROSSPLANE_CLI_VERSION = v1.17.1
-
--include build/makelib/k8s_tools.mk
-# ====================================================================================
-# Setup XPKG
-XPKG_DIR = $(shell pwd)
-XPKG_IGNORE = .github/workflows/*.yaml,.github/workflows/*.yml,examples/*.yaml,.work/uptest-datasource.yaml,.cache/render/*
-XPKG_REG_ORGS ?= xpkg.upbound.io/upbound
-# NOTE(hasheddan): skip promoting on xpkg.upbound.io as channel tags are
-# inferred.
-XPKG_REG_ORGS_NO_PROMOTE ?= xpkg.upbound.io/upbound
-XPKGS = $(PROJECT_NAME)
--include build/makelib/xpkg.mk
-
 CROSSPLANE_VERSION = v1.17.1-up.1
+UPTEST_VERSION = v1.1.2
+
+# Crossplane Configuration
+# ------------------
 CROSSPLANE_CHART_REPO = https://charts.upbound.io/stable
 CROSSPLANE_CHART_NAME = universal-crossplane
 CROSSPLANE_NAMESPACE = upbound-system
 CROSSPLANE_ARGS = "--enable-usages"
 KIND_CLUSTER_NAME ?= uptest-$(PROJECT_NAME)
 
--include build/makelib/local.xpkg.mk
--include build/makelib/controlplane.mk
-
-# ====================================================================================
-# Testing
+# XPKG Configuration
+# ------------------
+XPKG_DIR = $(shell pwd)
+XPKG_IGNORE = .github/workflows/*.yaml,.github/workflows/*.yml,examples/*.yaml,.work/uptest-datasource.yaml,.cache/render/*
+XPKG_REG_ORGS ?= xpkg.upbound.io/upbound
+# NOTE: Skip promoting on xpkg.upbound.io as channel tags are inferred
+XPKG_REG_ORGS_NO_PROMOTE ?= xpkg.upbound.io/upbound
+XPKGS = $(PROJECT_NAME)
 
-UPTEST_VERSION = v1.1.2
+# Testing Configuration
+# ------------------
 UPTEST_LOCAL_DEPLOY_TARGET = local.xpkg.deploy.configuration.$(PROJECT_NAME)
-UPTEST_DEFAULT_TIMEOUT = 2400s
+UPTEST_DEFAULT_TIMEOUT ?= 2400s
 
+# KCL Configuration
+# ------------------
+KCL_COMPOSITION_PATH ?= apis/kcl/generate.k
+LANG_KCL := $(shell find ./apis -type f -name '*.k')
+
+# Include makelib files
+# ------------------
+-include build/makelib/common.mk
+-include build/makelib/k8s_tools.mk
+-include build/makelib/xpkg.mk
+-include build/makelib/local.xpkg.mk
+-include build/makelib/controlplane.mk
 -include build/makelib/uptest.mk
 
 # ====================================================================================
 # Targets
+# ====================================================================================
 
-# run `make help` to see the targets and options
-
+# Initial Setup
+# ------------------
 # We want submodules to be set up the first time `make` is run.
 # We manage the build/ folder and its Makefiles as a submodule.
 # The first time `make` is run, the includes of build/*.mk files will
 # all fail, and this target will be run. The next time, the default as defined
 # by the includes will be run instead.
-fallthrough: submodules
+fallthrough: submodules  ## Initial setup and submodule initialization
 	@echo Initial setup complete. Running make again . . .
 	@make
 
-submodules: ## Update the submodules, such as the common build scripts.
+submodules:  ## Update the submodules, including common build scripts
 	@git submodule sync
 	@git submodule update --init --recursive
 
-# We must ensure up is installed in tool cache prior to build as including the k8s_tools machinery prior to the xpkg
-# machinery sets UP to point to tool cache.
-build.init: $(UP)
+# Build Targets
+# ------------------
+# We must ensure up is installed in tool cache prior to build as including the k8s_tools
+# machinery prior to the xpkg machinery sets UP to point to tool cache.
+build.init: $(UP)  ## Initialize build requirements
 
-# In case of building a composition with kcl, we must first render the composition-file
-KCL_COMPOSITION_PATH ?= apis/kcl/generate.k
-LANG_KCL := $(shell find ./apis -type f -name '*.k')
+# KCL Targets
+# ------------------
 ifdef LANG_KCL
-kcl: $(KCL) ## Generate KCL-based Composition
+kcl: $(KCL)  ## Generate KCL-based Composition
 	@$(INFO) Generating kcl composition
 	@$(KCL) $(KCL_COMPOSITION_PATH) 1>/dev/null
 	@$(OK) Generated kcl composition
 
-render: kcl
+render: kcl  ## Render the composition output
 build.init: kcl
 .PHONY: kcl
 endif
 
-render.test: $(CROSSPLANE_CLI) $(KCL) render
-	@echo find .cache/render -depth 1 -type f -name '*.yaml'
+# Testing Targets
+# ------------------
+render.test: $(CROSSPLANE_CLI) $(KCL) render  ## Test rendered compositions
 	@for RENDERED_COMPOSITION in $$(find .cache/render -maxdepth 1 -type f -name '*.yaml'); do \
 		$(INFO) "Testing $${RENDERED_COMPOSITION}"; \
 		export RENDERED_COMPOSITION; \
 		$(KCL) test test/ && \
 		$(OK) "Success testing \"$${RENDERED_COMPOSITION}\"!" || \
 		($(ERR) "Failure testing \"$${RENDERED_COMPOSITION}\"!" && exit 1); \
-	done; \
+	done
 
-.PHONY: check-examples
-check-examples: ## Check examples for sanity
+check-examples:  ## Validate package versions in examples match dependencies
 	@$(INFO) Checking if package versions in dependencies match examples
 	@FN_EXAMPLES=$$( \
 		find examples -type f -name "*.yaml" | \
@@ -176,7 +232,13 @@ check-examples: ## Check examples for sanity
 	fi;
 	@$(OK) Package versions are sane
 
+# Help Targets
+# ------------------
+help: help.local  ## Display this help message
+
 help.local:
+	@echo "Available targets:"
+	@echo
 	@grep -E '^[a-zA-Z_-]+.*:.*?## .*$$' Makefile | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
 
-.PHONY: uptest e2e render yamllint help.local
+.PHONY: uptest e2e render yamllint help help.local check-examples render.test