Rust

Rust Application Stack

The rust application stack is used to build and deploy rust applications and produce deployment-ready containers for the SCALE environment. The containers produced in this application stack share common requirements with other application stacks deployed to the SCALE environment. These shared requirements include:

• Security scanning for any vulnerabilities
• Code coverage scanning for test quality.
• Staging of the application container in the appropriate Docker container repositories and tagged according to SCALE conventions.
• Completion of Unit Testing and User Acceptance Testing
• Gated approvals before allowing deployments into pre-production and production environments.
• Audit trail and history of deployment within the SCALE CI/CD Pipeline

Because of the above-listed requirements, rust application stack is provided in order to support the build and deployment of rust applications in a manner that integrates with SCALE requirements and processes. The flow of deployment includes first a Continuous Integration stage of processing in a pipeline prior to deployment in the Continuous Deployment stages. The Continuous Integration stage focuses on building the application, running scans to check for test coverage and security vulnerabilities, and staging the container in the appropriate Docker repository ready for deployment. Subsequent pipeline stages deploy the application to the appropriate target Kubernetes spaces.

For details on getting started, see getting started.

For details on repository structure, see repository structure.

The source directory contains boilerplate code creating a rust 'hello-SCALE' boilerplate application.

For details on application configuration, see application configuration.

For details on CI/CD pipelines, see CI/CD pipelines.

For details on upgrading to Pipeline v4.7, see upgrading to Pipeline v4.7.

Why Rust?

Rust is blazingly fast and memory-efficient: with no runtime or garbage collector, it can power performance-critical services, run on embedded devices, and easily integrate with other languages. Rust's rich type system and ownership model guarantee memory-safety and thread-safety - enabling you to eliminate many classes of bugs at compile-time. Rust has great documentation, a friendly compiler with useful error messages, and top-notch tooling - an integrated package manager and build tool, smart multi-editor support with auto-completion and type inspections, an auto-formatter, and more.

Cargo

Rust applications are generally powered by Cargo: Rust package manager. Cargo downloads your Rust package's dependencies, compiles your packages or binaries and can make distributable packages. SCALE Rust appstack requires mandatory Cargo.toml file that contains rust application metadata including name, dependencies or dev-dependencies etc. See more keys and their definitions at Manifest Format. Please refer to The Cargo Book for further reading. Visit Rust community's crate registry crates.io for available crates.

Appplication Code

Source directory contains source code for the rust application. Apart from Cargo.toml file, sub-directory src is requied which contains application rust (*.rs) files and unit tests. Integration tests in case of complex application should be organized in saperate tests directory. Please refer to official documentation for recommended project structure. Boiler plate Hello-SCALE demostartes simplest example of actix-web framework.

For details on pipeline definition, see pipeline definition.

Application-Specific Pipeline Configuration

The extends YAML object is a complex object consisting of additional YAML objects. This object is used to extend the pipeline logic (referenced by the repository defined in the resources object) by (a) referencing the correct appstack pipeline entry point and (b) passing a set of YAML objects as parameters to influence the behavior of the pipeline to meet an application teams specific needs.

The extends YAML object consists of 2 objects beneath it:

• template
• parameters

The template YAML object is a single value set to the initial entry point for the v4.7 pipeline for the rust appstack, so it should always be defined as follows:

extends:
  template: devops/rust.yml@spaces

Please refer to upgrade document to know more about rust.yml@templates which holds required metadata for the pipeline.

The parameters YAML object is defined immediately following the template object and at the same indentation level. This is the object that requires the most attention and definition to be set up. The parameters YAML object includes multiple parameters which can be used to configure CI/CD pipeline. Primarily this object contains parameters used for application builds. A typical setting in here would be to define appVersion used to build the application, looking like the following (including all of the extends object preceding it):

extends:
  template: devops/rust.yml@spaces
  parameters:
    appVersion: 4.7.x

Code style and testing

Application build process runs rustfmt tool via cargo to verify quality Rust application code formatting according to style guidelines. Further runs all defined tests and calculates code coverage with cargo-tarpaulin. You can control style checks and tests in azure-pipelines.yaml.

parameters:
  appVersion: 4.7.x
  rustfmt: "true"
  cargotest: "true"

Though both the options are configurable it is strongly recommended not to set rustfmt and cargotest parameters unless absolutely nessesary.

SCALE Pipeline runs cargo build in release mode to achive optimal run time performance. To know more about optimized artifacts with the release profile see the profiles section.

Rust version

The rust default version used by SCALE pipeline is Rust 1.84.1. Optionally you can specify it as a parameters in azure-pipelines.yaml:

  parameters:
    appVersion: 4.7.0
    rust:
      version: "1.84.1"
      tarpaulinVersion: "0.31.5"

Official debian rust images are used to build the application but images could be bulky for running the built application itself. SCALE recommends a practice to use a multibuild docker setup where the executable is created in a builder step and then copied into a different, slimmer image. For example, default rust toolchain image used in the SCALE pipeline to compile and build the application is rust:1.50-buster and later during docker build copies application binary into base image debian:buster-slim to build much slimmer final image for faster deployments. For most of applications use cases just specifying rust version should be sufficient. (For advanced users: Both baseImage and toolchainImage can be configured in azure-pipelines.yaml if required.)

For details on defining hostspaces, see defining hostspaces.

For details on skipping deployments, see skipping deployments.

For details on Horizontal Pod Autoscaler, see Horizontal Pod Autoscaler.

For details on PVC for application stacks, see PVC for application stacks.

DR changes

With the introduction of pipeline v4.7, we have implemented DR capabilities that require changes in the Helm chart. Please refer to the document below for the necessary modifications and kindly update your Helm chart accordingly.

Getting Started with DR

Please refer to the following document to prepare your codebase for disaster recovery.

DR Config Map and Ingress Setup

For details on Pod Anti-Affinity, see Pod Anti-Affinity.

For details on detailed pipeline configuration, see detailed pipeline configuration.

For details on Kubernetes deployment objects, see Kubernetes deployment objects.

For details on troubleshooting, see troubleshooting.