feat: enforce pod switch, theme, update status crd

Signed-off-by: will <[email protected]>

Author: wcrum

README.md

@@ -2,7 +2,7 @@
 
 
 <p align="left">
-  <img width="200" height="200" src="./public/imageshift.png">
+  <img width="200" height="200" src="./imageshift-icon.svg" alt="ImageShift Logo">
 </p>
 
 
@@ -53,8 +53,8 @@ helm install \
 ### Prerequisites
 - go version v1.23.0+
 - docker version 17.03+.
-- kubectl version v1.11.3+.
-- Access to a Kubernetes v1.11.3+ cluster.
+- kubectl version v1.19+.
+- Access to a Kubernetes v1.19+ cluster (mutating webhooks required).
 
 ### To Deploy on the cluster
 **Build and push your image to the location specified by `IMG`:**
@@ -155,7 +155,15 @@ previously added to 'dist/chart/values.yaml' or 'dist/chart/manager/manager.yaml
 is manually re-applied afterwards.
 
 ## Contributing
-// TODO(user): Add detailed information on how you would like others to contribute to this project
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+### Quick Start for Contributors
+
+1. Fork and clone the repository
+2. Run `make test` to verify the test suite passes
+3. Create a feature branch and make your changes
+4. Submit a pull request
 
 **NOTE:** Run `make help` for more information on all potential `make` targets
 

api/v1/imageshift_types.go

@@ -40,6 +40,12 @@ type ImageshiftSpec struct {
 
 	// +default:value="imageshift.dev"
 	NamespaceSelector string `json:"namespaceSelector"`
+
+	// EnforceExistingPods when true, the controller will delete pods that have
+	// images not matching the swap rules. This forces pod recreation with correct images.
+	// Default: false (disabled)
+	// +optional
+	EnforceExistingPods bool `json:"enforceExistingPods,omitempty"`
 }
 
 type ImageshiftMapping struct {

api/v1/zz_generated.deepcopy.go

@@ -42,6 +42,12 @@ spec:
               default:
                 default: docker.io
                 type: string
+              enforceExistingPods:
+                description: |-
+                  EnforceExistingPods when true, the controller will delete pods that have
+                  images not matching the swap rules. This forces pod recreation with correct images.
+                  Default: false (disabled)
+                type: boolean
               mappings:
                 properties:
                   exactSwap:

config/crd/bases/imageshift.dev_imageshifts.yaml

@@ -8,13 +8,13 @@ Before installing ImageShift, ensure your environment meets the following requir
 
 ## Kubernetes Version
 
-- **Kubernetes 1.35+** is required
+- **Kubernetes 1.19+** is required
 - The mutating admission webhook API must be enabled (enabled by default)
 
 Verify your Kubernetes version:
 
 ```bash
-kubectl version --short
+kubectl version
 ```
 
 ## kubectl

docs/docs/installation/prerequisites.md

@@ -239,6 +239,15 @@ kubectl label namespace prod-api imageshift.dev=enabled
 kubectl label namespace dev-app imageshift.dev-
 ```
 
+## Registry Normalization
+
+ImageShift normalizes registry names to handle aliases. For example:
+
+- `docker.io` is equivalent to `index.docker.io` (Docker Hub's canonical name)
+- Images without a registry prefix (e.g., `nginx:latest`) use the `spec.default` registry
+
+This means you can use `docker.io` in your swap rules and it will match images specified as either `docker.io/nginx` or `nginx` (when default is `docker.io`).
+
 ## Tips for Writing Regex Patterns
 
 ### Escape Special Characters

docs/docs/reference/configuration.md

@@ -22,8 +22,9 @@ The Imageshift resource defines image mapping rules that are applied to pods cre
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `spec.default` | string | `"docker.io"` | The default registry for images without an explicit registry |
-| `spec.namespaceSelector` | string | `"imageshift.dev"` | The label key used to identify namespaces for image swapping |
+| `spec.default` | string | `"docker.io"` | The default registry assumed for images without an explicit registry prefix (e.g., `nginx` becomes `docker.io/library/nginx`) |
+| `spec.namespaceSelector` | string | `"imageshift.dev"` | Reserved for future use. Currently ignored - namespaces must use label `imageshift.dev=enabled` |
+| `spec.enforceExistingPods` | boolean | `false` | When enabled, the controller will delete pods that have images not matching the swap rules, forcing pod recreation with correct images |
 | `spec.mappings` | object | | Container for all mapping rules |
 
 ### Mappings
@@ -154,11 +155,38 @@ spec:
         target: "registry.internal.example.com/ecr/$1/$2/$3"
 ```
 
-## Namespace Selection
+## Enforcing Existing Pods
+
+By default, ImageShift only mutates pods at creation time via the admission webhook. Pods that already exist when ImageShift is installed or when rules are changed will not be affected.
+
+To enforce image swap rules on existing pods, enable the `enforceExistingPods` field:
+
+```yaml
+apiVersion: imageshift.dev/v1
+kind: Imageshift
+metadata:
+  name: imageshift
+spec:
+  enforceExistingPods: true
+  mappings:
+    swap:
+      - registry: docker.io
+        target: registry.internal.example.com/dockerhub
+```
 
-ImageShift only processes pods in namespaces that have the selector label set to `enabled`.
+:::warning
+**This is a disruptive operation.** When enabled, the controller will **delete** any pods in labeled namespaces that have images not matching the current swap rules. This forces the pods to be recreated by their controllers (Deployment, StatefulSet, etc.) with the correct images applied by the webhook.
 
-Default selector label: `imageshift.dev=enabled`
+Only enable this feature when you understand the impact:
+- Pods will be deleted and recreated
+- Stateless workloads managed by controllers will recover automatically
+- Standalone pods (not managed by a controller) will be permanently deleted
+- Brief service interruptions may occur during pod recreation
+:::
+
+## Namespace Selection
+
+ImageShift only processes pods in namespaces that have the label `imageshift.dev=enabled`.
 
 To enable a namespace:
 
@@ -172,29 +200,59 @@ To disable a namespace:
 kubectl label namespace my-namespace imageshift.dev-
 ```
 
-To use a custom selector label, set `spec.namespaceSelector`:
+:::note
+The `spec.namespaceSelector` field is reserved for future use. Currently, ImageShift always uses `imageshift.dev` as the label key.
+:::
+
+## Pod Annotations and Labels
+
+When ImageShift mutates a pod, it adds the following metadata:
+
+### Labels
+
+| Label | Value | Description |
+|-------|-------|-------------|
+| `imageshift.dev/mutated` | `true` | Added when at least one container image was swapped |
+
+### Annotations
+
+For each mutated container, ImageShift stores the original image reference:
+
+| Annotation Pattern | Description |
+|--------------------|-------------|
+| `<container-name>.container.imageshift.dev/original` | Original image for regular containers |
+| `<container-name>.initContainer.imageshift.dev/original` | Original image for init containers |
+
+Example for a pod with an nginx container:
 
 ```yaml
-spec:
-  namespaceSelector: custom-label.example.com
+metadata:
+  labels:
+    imageshift.dev/mutated: "true"
+  annotations:
+    nginx.container.imageshift.dev/original: "nginx:latest"
 ```
 
-Then label namespaces with:
+You can use these annotations to verify mutations or for debugging:
 
 ```bash
-kubectl label namespace my-namespace custom-label.example.com=enabled
+kubectl get pod <pod-name> -o jsonpath='{.metadata.annotations}' | jq .
 ```
 
 ## Limitations
 
 - Only one Imageshift resource can exist in the cluster at a time
 - The validating webhook rejects creation of additional Imageshift resources
-- Init containers and ephemeral containers are also processed
+- Init containers are also processed
 - Images in Pod templates (Deployments, StatefulSets, etc.) are processed when Pods are created
 
 ## Status
 
-The Imageshift resource does not currently expose status fields. Future versions may include:
-- Count of processed pods
-- Last reconciliation time
-- Error conditions
+The Imageshift resource exposes the following status fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `conditions` | array | Standard Kubernetes conditions for the resource |
+| `lastReconciled` | timestamp | When the resource was last successfully reconciled |
+| `configValid` | boolean | Whether the current configuration is valid |
+| `mutatedPodCount` | integer | Total number of pods that have been mutated |

docs/docs/reference/crd.md

@@ -45,7 +45,8 @@ const config = {
         title: 'ImageShift',
         logo: {
           alt: 'ImageShift Logo',
-          src: 'img/logo.svg',
+          src: 'img/imageshift-icon-light.svg',
+          srcDark: 'img/imageshift-icon-dark.svg',
         },
         items: [
           {

docs/docusaurus.config.js

@@ -56,6 +56,13 @@ export const schemaData = {
           default: 'imageshift.dev',
           description: 'The label key used to identify namespaces for image swapping',
         },
+        {
+          name: 'enforceExistingPods',
+          type: 'boolean',
+          required: false,
+          default: false,
+          description: 'When true, the controller will delete pods that have images not matching the swap rules, forcing pod recreation with correct images',
+        },
         {
           name: 'mappings',
           type: 'object',
@@ -139,8 +146,33 @@ export const schemaData = {
       name: 'status',
       type: 'object',
       required: false,
-      description: 'ImageshiftStatus defines the observed state of Imageshift (currently unused)',
-      children: [],
+      description: 'ImageshiftStatus defines the observed state of Imageshift',
+      children: [
+        {
+          name: 'conditions',
+          type: 'array',
+          required: false,
+          description: 'Standard Kubernetes conditions for the resource',
+        },
+        {
+          name: 'lastReconciled',
+          type: 'string',
+          required: false,
+          description: 'Timestamp of the last successful reconciliation',
+        },
+        {
+          name: 'configValid',
+          type: 'boolean',
+          required: false,
+          description: 'Whether the current configuration is valid',
+        },
+        {
+          name: 'mutatedPodCount',
+          type: 'integer',
+          required: false,
+          description: 'Total number of pods that have been mutated',
+        },
+      ],
     },
   ],
 };