Scylla Machine Image

This repository provides tools to:

• Create cloud machine images with pre-installed Scylla
• Configure Scylla automatically on first boot via cloud-init
• Deploy Scylla clusters easily in cloud environments

Quick Start

Building Images

All cloud images are built using the unified packer/build_image.sh script.

Repository URL Format: Specify the repository URL without http:// or https:// prefix. The script automatically prepends https://.

Example repository URLs:

• Master branch: downloads.scylladb.com/unstable/scylla/master/deb/unified/latest/scylladb-master/scylla.list
• For custom repos, you can use the unified-deb Jenkins job to build repository packages if changes are made to boot scripts.

AWS

packer/build_image.sh \
  --target aws \
  --repo downloads.scylladb.com/unstable/scylla/master/deb/unified/latest/scylladb-master/scylla.list \
  --arch x86_64

AWS Credentials: Configure AWS credentials via environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION) or AWS CLI profile. Optionally customize settings in packer/ami_variables.json:

{
  "security_group_id": "sg-xxxxxxxxx",
  "region": "us-east-1",
  "associate_public_ip_address": "true",
  "instance_type": "c4.xlarge"
}

GCE (Google Cloud)

packer/build_image.sh \
  --target gce \
  --repo downloads.scylladb.com/unstable/scylla/master/deb/unified/latest/scylladb-master/scylla.list \
  --arch x86_64

GCE Credentials: Authenticate using gcloud auth application-default login or set GOOGLE_APPLICATION_CREDENTIALS environment variable. Configure settings in packer/gce_variables.json:

{
  "project_id": "your-project-id",
  "region": "us-central1",
  "zone": "us-central1-a",
  "instance_type": "n2-standard-2"
}

Azure

packer/build_image.sh \
  --target azure \
  --repo downloads.scylladb.com/unstable/scylla/master/deb/unified/latest/scylladb-master/scylla.list \
  --arch x86_64

Azure Credentials: Configure Azure credentials in packer/azure_variables.json:

{
  "client_id": "your-client-id",
  "client_secret": "your-client-secret",
  "tenant_id": "your-tenant-id",
  "subscription_id": "your-subscription-id",
  "region": "East US",
  "vm_size": "Standard_D4_v4"
}

OCI (Oracle Cloud Infrastructure)

packer/build_image.sh \
  --target oci \
  --repo downloads.scylladb.com/unstable/scylla/master/deb/unified/latest/scylladb-master/scylla.list \
  --arch x86_64

OCI Credentials: Configure OCI CLI with oci setup config or provide credentials in packer/oci_variables.json. See packer/oci/OCI_BUILD_GUIDE.md for detailed setup instructions.

Deploying Clusters

AWS CloudFormation

Deploy a Scylla cluster using CloudFormation. The template is a Jinja2 template that must be rendered first:

# Install jinja2-cli (if not already installed)
pip install jinja2-cli

# Render the template
jinja2 -D arch=x86_64 aws/cloudformation/scylla.yaml.j2 > scylla.yaml

# Deploy the stack
aws cloudformation create-stack \
    --stack-name my-scylla-cluster \
    --template-body file://scylla.yaml \
    --parameters ParameterKey=KeyName,ParameterValue=<your-key> ...

See aws/cloudformation/README.md for detailed instructions.

User-Data Configuration

Scylla machine images support configuration via cloud-init user-data in JSON or YAML format.

See cloud provider documentation for passing user-data:

• AWS: EC2 User Data
• GCE: Startup Scripts
• Azure: Custom Data
• OCI: Cloud-Init Scripts

Available User-Data Options

Option	Type	Default	Description
scylla_yaml	object	{}	Settings to pass to scylla.yaml (see Scylla YAML)
developer_mode	boolean	false	Enable developer mode
post_configuration_script	string	""	Script to run after configuration (can be base64 encoded)
post_configuration_script_timeout	integer	600	Timeout in seconds for post-configuration script
start_scylla_on_first_boot	boolean	true	Start scylla-server automatically on first boot
device_wait_seconds	integer	0	Max seconds to wait for storage devices (recommended: 300)

Scylla YAML Configuration

The scylla_yaml field passes settings directly to the Scylla configuration file. See the official Scylla YAML documentation for all available options.

Common settings with machine image defaults:

Setting	Default	Description
cluster_name	Auto-generated	Name of the cluster
auto_bootstrap	true	Enable auto-bootstrap
listen_address	Instance private IP	Address to listen on
broadcast_rpc_address	Instance private IP	RPC broadcast address
endpoint_snitch	Ec2Snitch (AWS)	Snitch for cloud topology
rpc_address	0.0.0.0	RPC listen address
seed_provider	Instance private IP	Seed node addresses

Example User-Data

JSON Format

{
  "scylla_yaml": {
    "cluster_name": "my-cluster",
    "seed_provider": [{
      "class_name": "org.apache.cassandra.locator.SimpleSeedProvider",
      "parameters": [{"seeds": "10.0.1.1,10.0.1.2"}]
    }]
  },
  "post_configuration_script": "#!/bin/bash\necho 'Configuration complete'",
  "start_scylla_on_first_boot": true,
  "device_wait_seconds": 300
}

YAML Format

scylla_yaml:
  cluster_name: my-cluster
  seed_provider:
    - class_name: org.apache.cassandra.locator.SimpleSeedProvider
      parameters:
        - seeds: 10.0.1.1,10.0.1.2
post_configuration_script: |
  #!/bin/bash
  echo 'Configuration complete'
start_scylla_on_first_boot: true
device_wait_seconds: 300

Using MIME Multipart (Advanced)

For complex scenarios requiring multiple cloud-init features, use MIME multipart format with x-scylla/json or x-scylla/yaml content type:

Content-Type: multipart/mixed; boundary="===============BOUNDARY=="
MIME-Version: 1.0

--===============BOUNDARY==
Content-Type: x-scylla/yaml
MIME-Version: 1.0
Content-Disposition: attachment; filename="scylla_config.yaml"

scylla_yaml:
  cluster_name: my-cluster
  seed_provider:
    - class_name: org.apache.cassandra.locator.SimpleSeedProvider
      parameters:
        - seeds: 10.0.1.1
start_scylla_on_first_boot: true

--===============BOUNDARY==
Content-Type: text/cloud-config
MIME-Version: 1.0
Content-Disposition: attachment; filename="cloud-config.txt"

#cloud-config
cloud_final_modules:
- [scripts-user, always]

--===============BOUNDARY==--

See cloud-init documentation for more details.

Building Packages

The repository includes scripts to build OS packages (RPM/DEB) that configure Scylla on first boot.

RedHat/CentOS - RPM

dist/redhat/build_rpm.sh --target centos7

Or using Docker:

docker run -it -v $PWD:/scylla-machine-image -w /scylla-machine-image --rm centos:7.2.1511 \
  bash -c './dist/redhat/build_rpm.sh -t centos7'

Ubuntu/Debian - DEB

dist/debian/build_deb.sh

Or using Docker:

docker run -it -v $PWD:/scylla-machine-image -w /scylla-machine-image --rm ubuntu:20.04 \
  bash -c './dist/debian/build_deb.sh'

Development

Setup

See SETUP.md for detailed development environment setup using uv.

Running Tests

make test              # Run all tests (excluding integration)
make test-validation   # Run validation tests only
make test-integration  # Run integration tests (requires AWS credentials)

Code Quality

make format  # Format code
make lint    # Run linters
make check   # Run all checks

Documentation

• AWS CloudFormation Deployment
• OCI Build Guide
• Development Setup

License

Apache-2.0 - See LICENSE for details.