Skip to content

Converting Read/Write Objects to Content Bundles

Overview

Users often create content directly in the DRP UX (profiles, parameters, stages, tasks, etc.) for testing and development. These objects are stored in the BackingStore as read/write objects. To package this content for reuse, version control, or distribution, it must be converted into a proper content bundle.

This guide covers two methods for converting BackingStore read/write objects into bundled content packs.

Prerequisites

  • Digital Rebar Platform v4.x or higher
  • drpcli installed and configured
  • Access to DRP endpoint API
  • drp-community-content installed on endpoint

Methods

The drpcli bundlize command exports BackingStore objects directly.

Export all writable objects:

Bash
drpcli contents bundlize BackingStore > my-content.yaml

Export with secure params (requires secrets key):

Bash
drpcli contents bundlize BackingStore --key=secrets-key.txt > my-content.yaml

Limitations: The bundlize command exports all objects including runtime-specific items that should be cleaned up manually.

Method 2: Using convert-readwrite-to-bundle.sh Script

The conversion script automates the cleanup process, removing runtime objects and preparing a clean content structure. The script is available as a template in drp-community-content.

What the script does:

  1. Downloads BackingStore contents from DRP endpoint
  2. Unpacks contents into directory structure
  3. Removes runtime objects (jobs, leases, alerts, batches, catalog items, endpoints, etc.)
  4. Removes machine-specific profiles
  5. Removes global profile
  6. Removes machines, clusters, and resource brokers
  7. Cleans up derived fields (Bundle, Endpoint, Errors, ReadOnly, timestamps, etc.)
  8. Creates stub meta.yaml for customization

Procedure

Generate the Script from Template

Similar to the OpenShift custom bundles pattern, render the template from DRP server:

Bash
# Create temporary machine for rendering context
drpcli machines create fake-machine

# Render template to generate script
drpcli templates render convert-readwrite-to-bundle.sh.tmpl Name:fake-machine > convert-readwrite-to-bundle.sh

# Clean up temporary machine
drpcli machines destroy Name:fake-machine

# Make script executable
chmod +x convert-readwrite-to-bundle.sh

Run the Script

Bash
# Configure drpcli access (if not already configured)
export RS_ENDPOINT=https://your-drp-endpoint:8092
export RS_KEY=username:password

# Run conversion
./convert-readwrite-to-bundle.sh

Script output:

Text Only
Cleaning up from previous script invocations...
Getting BackingStore (read/write objects) contents...
Unpacking contents...
Removing runtime objects...
Removing runtime profiles...
Removing global profile...
Removing runtime machines and other resources...
Making stub Meta Data file...
Clean up unnecessary object fields...

Result: Creates rw-content/ directory with cleaned objects and secrets-key.txt for secure params.

Customize Meta Data

Edit rw-content/meta.yaml with appropriate values:

YAML
---
Name: my-custom-content
DisplayName: My Custom Content
Author: Your Name
CodeSource: https://github.com/yourorg/content-repo
Color: blue
Description: Custom content pack for lab environment
DocUrl: https://docs.example.com/my-content
Icon: server
License: Apache-2.0
Prerequisites: drp-community-content
Source: https://github.com/yourorg/content-repo
Documentation: |
  # My Custom Content

  This content pack provides custom configurations for lab infrastructure.

  ## Features

  - Custom profiles for lab machines
  - Lab-specific parameters
  - Deployment workflows

  ## Usage

  Apply the `lab-baseline` profile to machines in your lab environment.

Review and Clean Up

Review plugins:

Bash
ls rw-content/plugins/

Remove any plugins that aren't actually needed for this content pack.

Review params:

Bash
ls rw-content/params/

Ensure all parameters are intentional and documented.

Review profiles:

Bash
ls rw-content/profiles/

Verify no machine-specific profiles remain.

Bundle the Content

Bash
cd rw-content
drpcli contents bundle ../my-content.yaml Version=v1.0.0

With semantic versioning:

Bash
drpcli contents bundle ../my-content.yaml Version=v1.2.3

Installation

Initial Upload

Bash
drpcli contents upload my-content.yaml

Replace Writable Objects

To replace existing BackingStore objects with the bundled versions:

Bash
drpcli contents upload my-content.yaml --replace-writable

With secure params:

Bash
drpcli contents upload my-content.yaml --replace-writable --key=secrets-key.txt

Secure Parameters

The secrets-key.txt file is critical for managing secure parameters.

Key Points:

  • The key file is required for uploading and maintaining secure parameters at rest
  • Store the key securely - without it, encrypted secure params cannot be decrypted
  • Secure parameters are controlled by the Secure: true keyword and value in parameter yaml definitions
  • When Secure: true is set, clear text param values in the bundle will be automatically encrypted when uploaded to DRP with --key
  • Use the same key file consistently for bundle and upload operations

Validation

Verify Bundle Structure

Bash
# List contents
drpcli contents show my-custom-content

# Check objects
drpcli profiles list | grep -v "global\|machineSpecific"
drpcli params list
drpcli stages list

Test in Clean Environment

Deploy the content bundle in a test DRP endpoint:

Bash
# Upload to test endpoint
drpcli contents upload my-content.yaml

# Verify functionality
drpcli machines create '{"Name": "test-machine", "Profiles": ["lab-baseline"]}'

Troubleshooting

Script Fails with "No drpcli in PATH"

Ensure drpcli is installed and accessible:

Bash
which drpcli
# If not found:
curl -fsSL https://rackn-sledgehammer.s3.amazonaws.com/drpcli -o drpcli
chmod +x drpcli
sudo mv drpcli /usr/local/bin/

Bundle Upload Fails with Validation Errors

Check for invalid object references:

Bash
# Review bundle contents
drpcli contents document my-content.yaml | less

# Fix validation errors in source files
cd rw-content
# Edit problematic files
drpcli contents bundle ../my-content.yaml Version=v1.0.1

Secure Params Not Working

Verify secrets key is used consistently:

Bash
# Bundle with key
drpcli contents bundle my-content.yaml Version=v1.0.0 --key=secrets-key.txt

# Upload with same key
drpcli contents upload my-content.yaml --key=secrets-key.txt

Runtime Objects Still Present

Manually remove runtime objects:

Bash
cd rw-content
rm -rf activities alerts batches catalog_items endpoints ipmi_scan_results jobs leases preferences plugin_providers trigger_providers users work_orders
rm -rf machines clusters resource_brokers
rm -f profiles/global.yaml

# Remove machine-specific profiles
for machine in $(drpcli machines list --format=json | jq -r '.[].Name'); do
  rm -f profiles/$machine.yaml
done

Best Practices

Version Control

Add the content directory to git:

Bash
cd rw-content
git init
git add .
git commit -m "Initial content pack"
git remote add origin https://github.com/yourorg/content-repo
git push -u origin main

Semantic Versioning

Use semantic versioning for content releases:

  • v1.0.0 - Initial release
  • v1.1.0 - New features (backward compatible)
  • v1.0.1 - Bug fixes
  • v2.0.0 - Breaking changes

Document Parameters

Add clear documentation to each parameter:

YAML
Name: my-custom-param
Description: Controls widget behavior
Documentation: |
  # my-custom-param

  This parameter controls how widgets are configured.

  ## Values

  - `enabled` - Enable widgets (default)
  - `disabled` - Disable widgets
  - `auto` - Automatic detection

  ## Example

  ```yaml
  Params:
    my-custom-param: enabled
  ```
Schema:
  type: string
  enum: [enabled, disabled, auto]
  default: enabled

Organize Content Logically

Group related objects:

Text Only
rw-content/
├── meta.yaml
├── params/
│   ├── network-*.yaml      # Network-related params
│   ├── storage-*.yaml      # Storage-related params
│   └── app-*.yaml          # Application params
├── profiles/
│   ├── baseline.yaml       # Base profile
│   ├── network-config.yaml # Network profile
│   └── storage-config.yaml # Storage profile
├── stages/
├── tasks/
└── workflows/

Test Before Distribution

Create a test workflow:

Bash
cd rw-content
cat > workflows/test-content.yaml <<EOF
---
Name: test-my-content
Stages:
  - my-custom-stage
EOF

drpcli contents bundle ../my-content-test.yaml Version=v0.0.1
drpcli contents upload ../my-content-test.yaml

References