Installation

Overview

KubeCloudScaler can be installed using three different methods. Choose the one that best fits your deployment strategy:

Helm (Recommended): Best for production deployments with easy configuration management
Kustomize: Ideal for GitOps workflows and customized deployments
Manual: For development, testing, or when you need full control over the build process

Recommended for production environments

Install KubeCloudScaler

Install the operator using Helm with the official OCI registry:

helm upgrade --install kubecloudscaler \
  oci://ghcr.io/kubecloudscaler/charts/kubecloudscaler \
  --namespace kubecloudscaler-system \
  --create-namespace

Create Your First Scaler Configuration

Create a YAML file (e.g., my-scaler.yaml) with your scaling configuration:

# Example: Scale down all deployments in 'default' namespace during evening hours
apiVersion: kubecloudscaler.cloud/v1alpha3
kind: K8s
metadata:
  name: evening-scaledown
spec:
  periods:
    - type: "down"
      time:
        recurring:
          days:
            - all
          startTime: "19:00"
          endTime: "21:00"
          timezone: "Europe/Paris"
      minReplicas: 0
      maxReplicas: 10
  resources:
    types:
      - deployments
  config:
    namespaces:
      - default
    forceExcludeSystemNamespaces: true

Note

K8s, Gcp, and Flow CRDs are cluster-scoped resources. Do not set metadata.namespace.

Apply the Configuration

Deploy your scaler configuration:

kubectl apply -f my-scaler.yaml

Verify Installation

Check that the operator is running:

kubectl get pods -n kubecloudscaler-system
kubectl get k8s

Uninstall (Optional)

To remove KubeCloudScaler completely:

# Remove your scaler configurations first
kubectl delete k8s --all
kubectl delete gcp --all
kubectl delete flow --all

# Uninstall the Helm chart
helm uninstall kubecloudscaler -n kubecloudscaler-system

# Remove the namespace if desired
kubectl delete namespace kubecloudscaler-system

Ideal for GitOps workflows and infrastructure-as-code

Clone the Repository

git clone https://github.com/kubecloudscaler/kubecloudscaler.git
cd kubecloudscaler

Deploy Using Kustomize

Apply the default configuration directly from the repository:

kubectl apply -k config/default

This will:

Install the Custom Resource Definitions (CRDs)
Deploy the operator in the kubecloudscaler-system namespace
Set up necessary RBAC permissions
Configure admission webhooks

Customize Your Deployment (Optional)

Create your own kustomization file to customize the deployment:

# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

resources:
- https://github.com/kubecloudscaler/kubecloudscaler/config/default

# Add your customizations here
patches:
- path: custom-config.yaml

namespace: my-custom-namespace

Create Scaler Resources

Create your scaler configurations in separate YAML files and apply them:

kubectl apply -f my-scaler-configs/

Verify Installation

kubectl get pods -n kubecloudscaler-system
kubectl get crd | grep kubecloudscaler

Uninstall

Remove the deployment:

kubectl delete -k config/default

For development, testing, and custom builds

Prerequisites

Ensure you have the following tools installed:

Docker or Podman
kubectl configured for your cluster
make
Go 1.25+ (for local development)

Clone and Build

git clone https://github.com/kubecloudscaler/kubecloudscaler.git
cd kubecloudscaler

Build and Push Container Image

Build and push the container image to your registry:

make docker-build docker-push IMG=<your-registry>/kubecloudscaler:latest

Replace <your-registry> with your container registry (e.g., ghcr.io/yourusername).

Install Custom Resource Definitions

make install

Deploy the Operator

Deploy the operator using your custom image:

make deploy IMG=<your-registry>/kubecloudscaler:latest

Test with Sample Configurations

Apply the provided sample configurations:

kubectl apply -k config/samples/

Verify Deployment

Check that everything is working:

kubectl get pods -n kubecloudscaler-system
kubectl get k8s

Development Workflow

For active development, you can run the operator locally:

make run

This generates self-signed webhook certificates and runs the controller with debug logging.

Uninstall

Clean up the installation:

# Remove sample configurations
kubectl delete -k config/samples/

# Remove the operator deployment
make undeploy

# Remove CRDs (this will delete all scaler resources!)
make uninstall

Next Steps

After installation, you can:

Configure your first scaler – See the Usage Guide for detailed configuration examples
Monitor scaling operations – Check the operator logs and resource events
Set up multiple scalers – Create different scaling policies for different applications or environments
Orchestrate with Flows – Use the Flow resource to coordinate multi-resource scaling

Troubleshooting

Common Issues

Operator not starting: Check the logs with kubectl logs -n kubecloudscaler-system deployment/kubecloudscaler-controller-manager

Permissions issues: Ensure your cluster has the necessary RBAC permissions for the operator. The Helm chart and kustomize manifests include the required ClusterRole and ClusterRoleBinding.

CRD conflicts: If upgrading, ensure old CRDs are properly updated. KubeCloudScaler supports multiple API versions (v1alpha1, v1alpha2, v1alpha3) with automatic conversion.

Webhook errors: If you see webhook-related errors, ensure cert-manager is installed or that webhook certificates are properly configured.

Metrics