ShareKube CRD API Reference

This page documents the ShareKube Custom Resource Definition (CRD) API.

API Version

apiVersion: sharekube.dev/v1alpha1
kind: ShareKube

Schema

Metadata

Standard Kubernetes resource metadata.

Field	Type	Description
name	string	Unique name for the preview environment
namespace	string	Default source namespace for resources (used if resource namespace is omitted)

Spec

Field	Type	Required	Description
targetNamespace	string	Yes	Destination namespace where resources will be copied
ttl	string	Yes	Time-to-live (TTL) for the preview environment (e.g., 1h, 24h, 7d)
resources	Resource[]	Yes	List of resources to be copied
transformationRules	TransformationRule[]	No	Future feature: Rules for modifying resources during copy
targetCluster	TargetCluster	No	Future feature: Remote cluster configuration
accessControl	AccessControl	No	Dynamic permission settings for resource access

Resource

Field	Type	Required	Description
kind	string	Yes	Kind of the Kubernetes resource (e.g., Deployment, Service)
name	string	Yes	Name of the resource to copy
namespace	string	No	Source namespace of the resource. If omitted, defaults to the ShareKube CRD's namespace

TransformationRule (Future Feature)

Field	Type	Required	Description
kind	string	Yes	Kind of resource to apply transformations to
removeFields	string[]	No	List of fields to remove from the resource (using dot notation)

TargetCluster (Future Feature)

Field	Type	Required	Description
name	string	Yes	Name of the target cluster
kubeconfigSecret	string	Yes	Name of the Secret containing kubeconfig for the target cluster

AccessControl

Field	Type	Required	Description
restrict	boolean	No	Enable fine-grained dynamic permissions (default: false)
allowedSourceNamespaces	string[]	No	List of namespaces that can be used as sources
allowedTargetNamespaces	string[]	No	List of namespaces that can be used as targets

Example

apiVersion: sharekube.dev/v1alpha1
kind: ShareKube
metadata:
  name: my-preview          # Unique name for the preview environment
  namespace: dev            # Default source namespace for resources (used if namespace is omitted)
spec:
  # Future extension: possibility to copy resources to a remote cluster.
  # Uncomment and configure the targetCluster section when remote support is implemented.
  # targetCluster:
  #   name: aws-dev
  #   kubeconfigSecret: aws-kubeconfig-secret
  targetNamespace: preview  # Destination namespace where the resources will be copied
  ttl: 1h                   # Time-to-Live (TTL) for the preview environment
  resources:
    # Case 1: Explicit namespace provided (the same as the CRD's namespace "dev")
    - kind: Deployment
      name: my-app-deployment
      namespace: dev      # Source namespace explicitly set to "dev"
      
    # Case 2: Explicit namespace provided (a different one, e.g., "config")
    - kind: ConfigMap
      name: my-app-config
      namespace: config   # Source namespace explicitly set to "config"
      
    # Case 3: Namespace omitted; the operator should use the default source namespace ("dev")
    - kind: Service
      name: my-app-service
      # 'namespace' is omitted, so the operator should assume the default source namespace ("dev")
      
  # Enables dynamic permissions for enhanced security
  accessControl:
    restrict: true      # Enable fine-grained permission creation
    allowedSourceNamespaces:
      - dev
      - config
    allowedTargetNamespaces:
      - preview-*
      
  # transformationRules: This section is a planned future improvement.
  # It will enable dynamic manipulation of the manifest by removing fields that might cause conflicts,
  # such as auto-generated fields (e.g., spec.clusterIP, spec.clusterIPs, and status for Service objects).
  # The block is currently commented out.
  # transformationRules:
  #   - kind: Service
  #     removeFields:
  #       - spec.clusterIP    # Remove clusterIP so the cluster can assign a new one in the destination namespace
  #       - spec.clusterIPs   # Remove clusterIPs for multi-IP services
  #       - status            # Remove status as it is auto-generated by Kubernetes

Resource Handling Behavior

Namespace Resolution

ShareKube resolves the source namespace for each resource using the following logic:

1. If namespace is explicitly set on the resource, use that namespace
2. If namespace is omitted, use the namespace of the ShareKube CRD

Resource Selection

Resources are selected based on their kind and name in the specified namespace.

TTL Processing

The ttl field specifies how long the preview environment should exist. After the TTL expires, the ShareKube operator will:

1. Delete all copied resources from the target namespace
2. Set the ShareKube CRD status to indicate completion
3. Not delete the target namespace itself (this should be handled separately)

Dynamic Permissions

When accessControl.restrict is set to true, ShareKube will:

1. Create fine-grained Roles and RoleBindings in both source and target namespaces
2. Only grant permissions for the exact resource types being copied
3. Use read-only permissions in source namespaces and full permissions in target namespaces
4. Clean up permissions automatically when the ShareKube resource is deleted

For more details, see the Dynamic Permissions documentation.

Resource Tracking and Cleanup

Since Kubernetes owner references don't work across namespaces, ShareKube uses a minimalist label-based approach to track and clean up resources:

1. All copied resources are labeled with just two ownership labels:

   • sharekube.dev/owner-name: <sharekube-name> - Links to the ShareKube resource that created it
   • sharekube.dev/owner-namespace: <sharekube-namespace> - Namespace of the ShareKube resource

2. When a ShareKube resource expires or is deleted, the operator uses these labels to find and delete all copied resources in the target namespace.

Error Handling

If a resource cannot be copied, the ShareKube operator will:

1. Log the error
2. Continue copying other resources
3. Update the ShareKube CRD status to indicate partial success

Status

The ShareKube CRD also includes a status section that provides information about the copying process:

status:
  phase: Ready              # Initializing, Processing, Ready, Error
  creationTime: "2023-..."  # Timestamp when the copy process started
  expirationTime: "2023-..." # Timestamp when the TTL will expire
  copiedResources:          # List of resources that were successfully copied
    - "Deployment/default/my-app"
    - "Service/default/my-app-svc"
  dynamicPermissions:       # List of dynamic permissions created for this ShareKube
    - "dev/sharekube-my-preview-source"
    - "preview/sharekube-my-preview-target"
  conditions:               # List of conditions for more detailed status
    - type: ResourcesCopied
      status: "True"
      reason: "AllResourcesCopied"
      message: "All resources were successfully copied"