Introduction

The Akraino technical project has been established as Akraino Project a Series of LF Projects, LLC (alternatively, the “Project”).  LF Projects, LLC is a Delaware series limited liability company.  Governance for the Project is detailed within the Project Technical Charter available at akraino.org (“Technical Charter”).  This Technical Community Document is intended to provide additional operational guidelines for the Project, and is subject to the Technical Charter.

1   Guiding Principles 

The Akraino Project a Series of LF Projects, LLC (“Akraino”) will operate transparently, openly, collaboratively, and ethically. Project proposals, timelines, and status must not merely be open, but also easily visible to outsiders.

2   Structure of the Technical Community

The Technical Community consists of multiple projects and a Technical Steering Committee that spans across all projects.

2.1   Technical Mission of Akraino

The Akraino Technical mission to focus on following areas

1. Create end to end configuration for a particular Edge Use case which is complete, tested and production deployable meeting the use case characteristics {Integration Projects - Blueprints}.
   Production deployable means the blueprint has passed unit and integration testing and meets the blueprint’s use case characteristics.

2. Develop projects to support such end to end configuration. Leverage upstream community work as much as possible to avoid duplication.  {Feature Projects}

3. Work with broader edge communities to standardize edge apis {Upstream Open Source Community Coordination - For example, Socialization, so community tools and Blueprints can interoperate. This work can be a combination of an upstream collaboration and development within the Akraino community [i.e. a feature project]}

4. Encourage Vendors and other communities to validate Edge applications and Virtual Network Functions on top of Akraino blueprints {Validation Project - ensures the working of a Blueprint}

In order to have focused work in support of initial releases, the Akraino community preference is to support Edge Blueprints related to enterprise and industrial IoT, and carrier edge network use cases. Board has the authority to define, modify, prioritize any additional industry sectors that need to be supported by the Akraino releases.

The Edge cloud stack placement could vary between Telco Offices to Customer premise and anything in between. Akraino community blueprints should be capable to deploy and address different edge cloud placement options. 

As an example, the picture below illustrates the enterprise edge and carrier edge network Edge use cases and possible edge placement.

Open

Figure 1 - Sector 1: Carrier edge network edge use case and edge placement

Open

Figure 2 - Sector 2: Enterprise and Industrial IoT use cases

3   Per Project

3.1   Project Roles 

3.1.1   Contributor

A Contributor is someone who contributes to a project. Contributions could take the form of code, code reviews,Wiki and documentation contributions,  Jira activities or other artifacts. Contributors work with a project’s Committer and the project’s sub-community. A Contributor may be promoted to a Committer by the project’s Committers after demonstrating a history of contributions to that project.

3.1.2   Committer

For each project there is a set of Contributors approved for the right to commit code to the source code management system (the “Committers”) for that project. 

• Committer rights are per project; being a Committer on one project does not give an individual committer rights on any other project.

• The Committers will be the decision makers on all matters for a project including design, code, patches, and releases for a project.

• Committers are the best available individuals, but usually work full-time on components in active development.

• All project committers information such as name, company, and Contact information should be documented in the wiki under the project.

In order to preserve meritocracy in selection of Committers while ensuring diversity of Committers, each initial project is encouraged to take on at least two Committers from different companies (subject to meritocracy).

3.1.3   Project Technical Leader

A project is required to elect a Project Technical Leader (“PTL”). The PTL acts as the de facto spokesperson for the project (feature projects and integration projects). 

3.1.3.1   Project Technical Leader Candidates

Candidates for the project’s Project Technical Leader will be derived from the Committers of the Project.

Candidates must self nominate.

3.1.3.2   Project Technical Leader Voters

Only Committers for a project are eligible to vote for a project’s Project Technical Lead.

3.1.3.3   Project Technical Leader Election Mechanics

An election for Project Technical Leader occurs when any of the following are true:

• The project is initially created

• The Project Technical Leader resigns his or her post

• The majority of committers on a project vote to call a new election

• One year has passed since the last Project Technical Leader election for that project

3.2   Project Operations

3.2.1   Project Decisions Making Process

Technical and release decisions for a project should be made by consensus of that project’s Committers.  If consensus cannot be reached, decisions are taken by majority vote of a project’s Committers.  Committers may, by majority vote, delegate (or revoke delegation) of any portion of such decisions to an alternate open, documented (wiki), and traceable decision making process.

3.2.2   Committer Lifecycle

3.2.2.1   Adding Committers

• Initial Committers for a project will be specified at project creation 

• Committer rights for a project are earned via contribution and community trust. Committers for a project select and vote for new Committers for that project.

• New Committers for a project should have a demonstrable established history of meritocratic contributions.

3.2.2.2   Adding Committers to moribund projects

In the event that a project has no active committers (e.g., due to resignations, etc.), the TSC may appoint an interim Committer from a project’s active Contributors. This term shall last until the next release date, after which time the Committer must stand for election from amongst other Committers on the project to maintain his or her status.  In this special case, approval requires a majority of committers who respond within two weeks. If no one responds by the deadline, then the committer status is approved. This provision allows a project to continue development following an unexpected change in personnel.

The method by which the TSC appoints an interim Committer is first by request to the Akraino-TSC email list indicating the request to appoint an interim Committer for a project.  After the reception of such an email, the normal TSC decision process applies.

3.2.2.3   Removing Committers

A Committer may voluntarily resign from a project by making a public request to the PTL to resign (via the project email list and cc to tsc@lists.akraino.org ).

A Committer for a project who is disruptive, or has been inactive on that project for an extended period (e.g., six or more months) may have his or her Committer status revoked by the project’s Project Technical Leader or by 2/3 supermajority vote of the project’s committers.

The Project Technical Leader is responsible for informing the Technical Steering Committee (TSC) of any committers who are removed or resigned via the email list: tsc@lists.akraino.org.

Former committers removed for reasons other than being disruptive may be listed as ‘Emeritus Committers’.  That title expresses gratitude for their service, but conveys none of the privileges of being a Committer.

3.3   Project Lifecycle

3.3.1   Akraino Project Lifecycle

The activities of the Akraino community are articulated around projects and releases. The scope of each project is aligned with Akraino’s charter and the scope of each release is defined with the objective to fulfill a particular Edge use case(s).

A project is a long term endeavor setup to deliver features across multiple releases, which have a shorter lifespan. The project and release lifecycle should provide sufficient visibility to all community members and  allow teams to coordinate with one another.

This document covers the Akraino project lifecycle. The Release Lifecycle will be documented in the  wiki.

3.3.2   Akraino Project Types

Akraino will support three categories  of projects and upstream coordination activities related to the projects as shown in Figure 3 and further illustration are available under the section 3.3.2.1, 3.3.2.2 and 3.3.2.3 of this document.

The Akraino Community goal is to deliver fully integrated and production deployable solution for the users.  The combination of Feature projects (developing missing edge functionalities on non-upstream open source components), Integration projects (integrated end to end stack) and End To End (ETE) validation projects of the blueprints along with edge applications running on top of it, delivers the production deployable solution needed by the industry.

Akraino community uses upstream-first principle to avoid technical debt on the upstream open source components: Akraino projects should not carry patches against upstream projects, but collaborate with and contribute designs and patches to the respective upstream projects to address gaps. Exceptions must be approved by the TSC.

Open

Figure 3 – Akraino Project Types & Scope

3.3.2.1   Akraino Feature Projects  (a.k.a Development Project)

The Akraino Feature projects develop edge features, functionalities, interfaces and modules required by an Akraino blueprint or multiple Akraino blueprints to satisfy the Edge use cases and requirements. Feature projects focus on the development work required by Akraino community instead of upstream open source components.

Examples of Feature Projects include Akraino Portal and Workflows to support common user experience, Blueprint testing modules or suites, Operational tools, Edge SDKs and APIs, etc..

It is a long term endeavor set up to deliver features across multiple releases, which have a shorter lifespan.

The feature project should address the functionality needed by Akraino specified use cases. During the feature project creation the scope should define whether it will support a single or multiple blueprints. Illustration is shown on Figure 4.

Open

Figure 4 – Relationship between Feature Project, Upstream component and Integration project

3.3.2.2   Akraino Integration Projects (Blueprints)

Akraino Integration Projects create or modify Akraino Blueprints to support specific edge use cases. 

A Blueprint is a declarative configuration of an edge Cloud Stack that includes a combination of infrastructure hardware components, software components, Point of Delivery (POD) options, tools to manage the life cycle and CI/CD to manage the blueprint’s code. The blueprint should be production deployable to support one or more Edge applications or Virtual Network Functions (VNFs).

A Blueprint family is a collection of blueprints that share common characteristics and numerous POD types. For example, Network Cloud is a family of blueprints to support any Telco Virtual Network Functions (VNFs). Network Cloud - Unicycle A is a blueprint that supports Unicycle POD and Network Cloud - Rover A is a blueprint which delivers single server POD.

Akraino Blueprints must include the description of the Edge use cases that articulates the desired business outcome, workload characteristics, design constraints, and operational cost ranges.

The Blueprint can either develop or use the upstream lifecycle management (LCM) tools and deployment automation to support the installation of the Blueprints.  All Blueprints need to be tested by the Akraino community to prove that Edge applications and/or VNFs can operate effectively on the Blueprint as requested in the use case . 

Community members will use a template for use case characteristics, blueprint family and blueprint approved by the TSC to describe the hardware, software, deployment configurations, workload characteristics when requesting the creation or modification of an Akraino Blueprint. The requestor should demonstrate the following aspects to the TSC:

1. Each initial blueprint is encouraged to take on at least two Committers from different companies

2. Complete all templates outlined in this document

3. A lab with exact configuration required by the blueprint to connect with Akraino CI and demonstrate CD. User should demonstrate either an existing lab or the funding and commitment to build the needed configuration.

4. Blueprint is aligned with the Akraino Edge Stack Charter

5. Blueprint code that will be developed and used with Akraino repository should use only Open Source software components either from upstream or Akraino projects.

6. For new blueprints submission, the submitter should review existing blueprints and ensure it is not a duplicate blueprint and explain how the submission differs . The functional fit of an existing blueprint for a use case does not prevent an additional blueprint being submitted.

After TSC review and approval of community member request, an integration Project will be launched to develop the Blueprint. In some cases, community may decide to support single or multiple family of blueprints for a use case depending upon the need and interest (Subject to TSC approval). A blueprint or blueprint family may address one or more Edge use cases.

TSC will decide which blueprints or blueprints family to include into a release based on the maturity status of an individual blueprint within a Blueprint family. Maturity of a blueprint is demonstrated with full CD deployment using a validation project and should have addressed the use case for which the blueprint was created.  A release could support multiple blueprints. It is a long term endeavor set up to deliver a blueprint across multiple releases, which have a shorter lifespan.

Blueprint Specifications ultimately define the declarative configuration for each deployment model or Point of Delivery (POD) of a Blueprint.  The Point of Delivery (POD) defines the method in which a blueprint is deployed to an edge site.  PODs organize edge devices for deployment and enable a cookie-cutter approach to large scale deployments (e.g., 10,000 plus locations) at a reduced cost.  For example, an edge location could have a single server or multiple servers in one or more racks.  Blueprint families use YAML or similar configuration files.  The use of YAML files with different manifest file contents will allow for different configurations within the same Akraino blueprint family. 

The below diagram (Figure 5) illustrates the process.

Open

Figure 5 – Akraino Blueprint Creation Process

3.3.2.2.1   Akraino Blueprint Family and Life Cycle of Blueprints

At the Family level, blueprints are differentiated by high level technical attributes which are immutable. Removing or inserting one of these attributes would change any pod delivered by the blueprint to such an extent that it could not reasonably be considered part of the same blueprint family.

For example if a given blueprint family has a Family attribute of deploying a kubernetes based undercloud in a given Akraino release then any pod delivered by that blueprint must also do so.

The decision as to what technical attributes should define the blueprint family will be specific to each blueprint family (and release) and be approved by the TSC.

Each blueprint family should be flexible enough to allow reasonable variation to encourage  widespread deployment without requiring the introduction of a new blueprint family. For example, the decision to use Ubuntu or CentOS as the operating system in the Network Cloud blueprint family, should not require a different blueprint family to be introduced instead just different POD configuration (Rover with Ubuntu vs. Rover with CentOS)

The ultimate and final level of classification must be sufficiently definitive to allow any user to reliably deploy a duplicate pod in their own environment. This level of blueprint specification does not prevent a deployable entity (POD) from having a range of possible values (for example Ubuntu 16.X). This ultimate level of technical classification is termed the blueprint Species. 

Akraino releases will verify blueprints at this ultimate species level of technical specification to allow reliable and repeated pod replication.

Blueprint taxonomy of technical specification:

→ Family

                → Species (a.k.a blueprint, from which a replica pod can be deployed by anyone)

At the very minimum there would need to be one fully specified and thus deployable pod within a blueprint family (i.e. one species/POD of the blueprint). The number of species within a blueprint family may grow or diminish with Akraino releases.

Note: Specific named examples have been used in this section to help clarify. The use of “Network Cloud”  as example only reflects the fact this blueprints had been submitted to Akraino when written.

A use case may be supported by one or more blueprint families i.e. there is not a 1:1 mapping from an Akraino use case to Blueprint families. Likewise a given Akraino blueprint may support multiple Akraino use cases. An example of a Blueprint family are Network Cloud.

Below picture illustrates the Network Cloud blueprint family and POD level specification which allows possibility of different component level.

Open

Figure 6 - Illustration of blueprint family and its blueprints

3.3.2.2.2   Akraino Use Cases, blueprint families and blueprints

Akraino use cases are business driven and must include a clear description of business requirements, operational considerations (cost, user interface, scale, power restrictions, etc…) , and applications expected to operate on the Blueprint. Any community member can submit a use case for review by TSC for further development.

The submitter should use the appropriate templates as described below for the creation or modification of blueprint families or blueprints for TSC review.

Use case template and blueprint family templates are required when requesting creation or modification of a blueprint family.

Blueprint templates are required to create or modify blueprints within a blueprint family.  In some cases, new or modification to a blueprint may require updates to existing use case templates and/or blueprint family templates and the submitter should make changes to all 3 templates as required.

Open

Figure 7 - Templates needed for blueprint family and blueprint creation and modification

When one or more fully defined blueprint addresses the same use case common test cases should be adopted where possible.

Below are the sample templates of a target family of blueprints and the full template will be maintained on the wiki. Certain attributes shall be defined as informational only. For example cost targets whilst key should not be used to pass or fail the verification of a blueprint

3.3.2.2.2.1   Template 1 - Use case template

Below is a sample Use case template. The full template will be maintained on the Akraino Wiki.

 3.3.2.2.2.2   Template 2 - Blueprint family template

Below is a sample Blueprint family template. The full template will be maintained on the Akraino Wiki.

 3.3.2.2.2.3   Template 3 - Blueprint species template

Below is a sample Blueprint template defining an Akraino species. The full template will be maintained on the Akraino Wiki.

3.3.2.3   Akraino Validation Projects

Multiple labs will be used to validate Akraino projects to ensure production quality of blueprint and/or feature project releases. The Community CI lab is owned by the Akraino community and LF. In addition a number of Edge Validation labs are owned by an Akraino community company, organization or participant.

Comprehensive validation of the blueprint within the community will include testing of the OS layer, the undercloud layer, the upper cloud layer, VNF layer and the application layer. Test results should be available to the Akraino community for review via automated push to the wiki.  Any defects identified should be logged in JIRA and assigned to the responsible party.  When defects are identified in upstream components, Akraino coordinators should be assigned defect ownership.  Akraino coordinators will work with upstream communities to resolve defects. For defects that do not involve upstream communities, impacted Protect Technical Leaders should be assigned defect ownership.

Akraino Validation Projects will also include testing of Akraino releases.

An automation framework should be used for test procedures and leverage existing test automation suites for upstream projects as required.  It is the responsibility of the blueprint submitter to ensure that the Edge Validation and Community CI labs can support comprehensive validation of the blueprint and cover all use case characteristics.  

The TSC subcommittees tasked with the setup and structuring of operating procedures for the validation labs shall work to define the licensing requirements for the external labs.

3.3.2.3.1   Feature project unit testing in Community CI lab

The Akraino Community CI labs are owned by the Akraino community and LF. Access is controlled by LF best practices.

TSC will propose a subcommittee to maintain and coordinate the Community CI lab.

The following would be conducted in the Community CI lab:

• Unit testing of Feature projects or

• Integration of Feature projects to a blueprint

• Upstream projects together in the support of Akraino Blueprints.

 A full CD that works with the Akraino CI pipeline should be included in the validation project.

3.2.2.3.2   Blueprint and application testing in Akraino Edge Validation lab

Akraino Edge Validation labs are owned by an Akraino community company, organization or participant.

The Validation labs can be owned and operated by the supplier of the lab with limited access or no access to the hardware but results of the validation testing need to be shared to the community.

TSC will propose a subcommittee to maintain and coordinate the Validation labs.

Blueprint, application and VNF testing may be performed over a number of Validations labs concurrently in a coordinated manner as required.

• The Validation labs should be able to connect to Akraino Edge Stack CI hosted by LF to pull in Akraino blueprints for the validation. Necessary Firewalls can be opened by the Akraino Community on request.

• All Validation labs should be available most of the year for the community use and if the lab is not used for validation more than 3 consecutive months then it will be removed from the community list.

• Hardware and Network configuration used within the Validation labs should be declared and information should be documented in the wiki

• All the Validation labs addition, modifications or removable need to be approved by TSC

• All historic results (minimum of 1 year) of blueprint validation, Applications and VNF testing should be maintained in the wiki.

3.2.2.3.2.1   Blueprint testing

The test plan and associated test cases to validate the blueprint will be published on the Akraino wiki and reviewed by blueprint stakeholders.  

• The lab configuration should support functional, performance, security, and other test cases for the blueprint and cover the full stack for the blueprint. 

• Any license or support beyond the Community supplied software should be funded, owned and operated by the Validation supplier

Open source test tools and vendor tools with appropriate configurations should drive test traffic profiles that mimic in-scope use cases.  Akraino coordinators will engage upstream open source communities to get access to upstream community labs for the Akraino blueprint test team.  The submitter is responsible to establish access to necessary vendor labs.

3.2.2.3.2.2   Application and VNF testing

Akraino blueprint releases ensure that applications and virtual network functions (VNFs) can on-board and operate effectively on the Akraino solution. Validation labs can be further used for the validation of Edge applications and VNFs.

Application and VNF testing may take a number of forms including performance, scalability, security and usability, resilience etc.

Submission of results to the Akraino community is optional in case of commercially sensitive applications.

3.3.3   Project Lifecycle Overview

The project lifecycle provides the freedom for each team to conduct its project according to their needs, culture and work habits. Thus, the project lifecycle is not prescriptive on how each project operates.

Individual blueprint within a blueprint family shall not be tied to the overall Akraino release schedule (e.g. 6 months). An Akraino release can be composed of 1 to N fully verified blueprints or individual feature projects. As such the number of blueprints and contributing projects within a given Akraino release may vary overtime. Figure 8 show this with two blueprint families, Network Cloud and the imaginary Canis Edge and a number of individual blueprint species within each family.

Open

Figure 8 - Project and Akraino release lifecycles

Each project shall provide an expected release plan document published with the blueprint on the wiki.  From the project schedules an overall Akraino release schedule shall be maintained and published.

The project lifecycle process does not impose a duration for the project nor for individual project releases.

3.3.4   Project Lifecycle States and Reviews

Akraino projects’ life cycles defines five states that all three project goes through. A project lifecycle may extend across multiple projects and Akraino releases.
The procedure of moving from one state to the next one is independent from the Akraino release lifecycle and the pace depends on each individual project.

In order to effectively review project progress, four reviews are built-in to the project life cycle.

The life cycle of a project is depicted in the following diagram:

Open

Figure 9 – Akraino Project States

To move from one state to the next state, the Project Team has to formulate a Kick-Off release review to the TSC, by specifying its goal to move up the Project Lifecycle ladder.

Note 1: Project proposals are posted in the “Proposed Projects” section of the Akraino wiki.  Approved projects are posted to the “Approved Projects” section of the Akraino wiki.

The TSC will review each project proposal request and then vote to approve or reject.  Requestors should identify the different Point-of-Delivery options that should be enabled via the Blueprint creation / modification request, explain the continuous integration / continuous deployment (CI/CD) methodology that will be used, explain the test framework that will be used for the Blueprint and define the automation that will be needed to deploy Akraino based on the Blueprint.

Note 2: The proposal submitter can decide to remove projects in “proposal” state that do not progress to incubation state.

3.3.5   Tailoring

A project’s release cycle may be tailored by allowing some exceptions to the normal release process. Tailoring may be initiated in two ways:

1. By the TSC voting members: TSC voting members reserves the right to allow changes to the process in order to meet criteria that were initially unknown.

2. By Project Team Lead: Any project team lead can email TSC voting members to request tailoring the process for a particular release. The key point in tailoring is to anticipate as much as possible, to justify the request, and document the request in the wiki.

Tailoring practices will be documented as we progress through our releases. The TSC should respond to requests in a timely manner.