SlapOS Best Practices & Guidelines

This summary of the best practices and guidelines for working with SlapOS covers key conventions, development practices and release procedures.

I. Key Conventions and Standards

A. Software:

1. Atomic Parameters:

   • Guideline: Use atomic parameters for instance configurations. Define parameters as granular and independent units (e.g., host, port separately) rather than combined or complex structures.
   • Rationale: Ensures modularity, flexibility, and easier management of configurations. Prevents conflicts and simplifies updates.

2. Backward Compatibility:

   • Guideline: Maintain backward compatibility when updating software or configurations.
   • Rationale: Ensures that existing deployments continue to function correctly after updates, reducing the risk of breaking changes.

B. Recipes:

1. Extend GenericBaseRecipe:

   • Guideline: When creating custom recipes, extend the GenericBaseRecipe class provided by SlapOS.
   • Rationale: Promotes consistency and maintainability across recipes. Ensures that common functionalities and error handling are inherited.

2. Fail Early and Provide Meaningful Error Messages:

   • Guideline: Implement robust error handling in recipes. Raise exceptions with clear, informative messages when errors occur.
   • Rationale: Facilitates debugging and troubleshooting. Helps users and developers quickly identify and resolve issues.

C. Components:

1. Modularize Patches and Dependencies:

   • Guideline: Organize patches and dependencies in a modular way within the component directory.
   • Rationale: Improves maintainability and reusability of components. Makes it easier to manage updates and track changes.

2. Clear, Representative Naming Conventions:

   • Guideline: Use descriptive and consistent names for components, files, and directories. Component names should match file names (e.g., component/foo/buildout.cfg for component foo).
   • Rationale: Enhances readability and makes it easier to navigate the codebase.

D. Testing:

1. Integrate Promises:
   • Guideline: Include at least one Promise in every Software Release to monitor instance health and functionality.
   • Rationale: Ensures that every instance is continuously monitored, and corrective actions are triggered automatically in case of failures. This is crucial for maintaining system reliability.
2. Regularly Test with Pinned Versions:
   • Guideline: Use pinned versions of dependencies during testing to ensure consistent results.
   • Rationale: Prevents unexpected issues caused by dependency updates. Ensures that tests accurately reflect the behavior of production environments.
3. Automated Systems:
   • Guideline: Integrate tests with automated CI/CD pipelines.
   • Rationale: Enables continuous testing and early detection of regressions.

II. Buildout and Development Practices

A. Buildout in SlapOS:

1. Profiles (software.cfg, instance.cfg.in):
   • Guideline: Use software.cfg to define how to install software and its dependencies. Use instance.cfg.in to define instance-specific configurations and parameters.
   • Rationale: Separates installation instructions from instance configuration, promoting reusability of Software Releases.
2. Recipes:
   • Guideline: Utilize Buildout recipes to automate tasks such as downloading files, compiling code, creating directories, and generating configuration files.
   • Rationale: Automates repetitive tasks and ensures consistency across deployments.
3. Extensions:
   • Guideline: Use Buildout extensions to modularize configurations and reference other profiles.
   • Rationale: Reduces duplication and promotes reuse of common configurations.

B. Developing Software Releases:

1. Structure:
   • Guideline: Organize Software Releases following a standard directory structure, including software.cfg for installation and instance.cfg.in for instantiation.
   • Rationale: Ensures consistency and makes it easier to understand and maintain Software Releases.
2. JSON Schemas:
   • Guideline: Use JSON schemas to define and document instance parameters.
   • Rationale: Provides a clear and structured way to specify input parameters and their expected types, improving usability and enabling automated form generation.
3. Modularization:
   • Guideline: Break down configurations into reusable components and recipes.
   • Rationale: Promotes code reuse, simplifies maintenance, and makes it easier to extend or customize Software Releases.
4. Promises:
   • Guideline: Employ Promises to monitor instance health and trigger corrective actions.
   • Rationale: Ensures that instances are continuously monitored and that problems are automatically addressed, improving system reliability.

C. Extending Software Releases:

1. Modify Configuration Files:
   • Guideline: Update software.cfg and instance.cfg.in to add new features, parameters, or components.
   • Rationale: Allows customization and extension of existing Software Releases to meet specific requirements.
2. Add New Components:
   • Guideline: Introduce new components (e.g., for log rotation with cron and logrotate) to enhance functionality.
   • Rationale: Enables the addition of new features without modifying the core Software Release.
3. Jinja2 Templates:
   • Guideline: Use Jinja2 templates to introduce dynamic configurations and parameters.
   • Rationale: Provides a flexible way to generate configuration files based on instance-specific parameters.
4. Reusability:
   • Guideline: Leverage existing recipes and extend base configurations to avoid duplication and promote consistency.
   • Rationale: Simplifies development and maintenance of Software Releases.

III. Release and Upgrade Procedures

A. Release Process:

1. Freeze Versions:
   • Guideline: Pin versions of all dependencies (eggs) and use tags for repositories to ensure reproducibility.
   • Rationale: Prevents unexpected changes from affecting deployments and ensures that the same software environment is used consistently.
2. MD5 Checksums:
   • Guideline: Generate and validate MD5 checksums for all downloaded resources.
   • Rationale: Ensures the integrity of downloaded files and prevents the use of corrupted or tampered resources.
3. Shacache:
   • Guideline: Pre-cache resources in Shacache to speed up deployments.
   • Rationale: Reduces build times and ensures that precompiled binaries are available for faster installation.

B. Testing and Quality Assurance:

1. Rigorous Testing:
   • Guideline: Thoroughly test installation and instantiation processes before releasing a new version.
   • Rationale: Ensures that the Software Release works as expected and that no regressions have been introduced.
2. Compliance:
   • Guideline: Ensure compliance with naming conventions, versioning policies, and monitoring requirements.
   • Rationale: Maintains consistency and quality across Software Releases.

C. Publication:

1. Merge to Master:
   • Guideline: Merge development branches into the master branch after thorough testing and review.
   • Rationale: Ensures that the master branch always contains the latest stable code.
2. Create Release Tag:
   • Guideline: Create a new tag for each release to mark a specific version of the Software Release.
   • Rationale: Provides a clear way to identify and track different versions of the software.
3. Automated Testing Pipelines:
   • Guideline: Add the new Software Release to SlapOS automated testing pipelines.
   • Rationale: Ensures that the software is continuously tested and that any issues are detected early.

IV. Naming Conventions and Coding Standards

A. Naming Conventions:

1. Software Releases:
   • Directory: slapos/software/[name]
   • Branches: Use topic-based names (e.g., feature-x, bugfix-y), not personal names.
2. Components:
   • Directory: /component/[name]
   • Main Section: Named like the component (e.g., [foo] for component foo).
   • File Name: Matches component name (e.g., component/foo/buildout.cfg).
3. Buildout Profiles:
   • Software Release: software.cfg
   • Instance Profiles: instance[ * ].cfg
   • Other Profiles: buildout.cfg
4. Sections and Parameters:
   • Use - (dash) instead of _ (underscore) in section and parameter names (e.g., [install-foo-bar]).
5. Instance Parameters:
   • Must be atomic (e.g., host, ip, port separately).
   • Maintain common parameter names (e.g., host, ip, port, url).

B. Coding Standards:

1. Recipes:
   • Extend from GenericBaseRecipe or GenericSlapRecipe.
   • Fail early with meaningful error messages.
   • Get SLAP parameters from the Buildout Instance Profile.
   • Publish SLAP connection parameters using the slapos.cookbook:publish recipe.
2. Promises:
   • Define a class called RunPromise that inherits from GenericPromise.
   • Implement sense(), test(), and anomaly() methods.
   • Use getConfig() to access configuration parameters.
3. General:
   • Avoid copy-pasting more than 30 lines of code.
   • Always pin versions of eggs/products.
   • Tag Software Releases for production.
   • Only release precompiled Software Releases for production.

Page last modified: 2025-01-03 08:36:57