Contributor/Developer Guide

In this section you will find information helpful for contributing to manila.

Basic Information

• So You Want to Contribute…
  • Where is the code?
  • Communication
    • IRC
    • Team Meetings
    • Mailing List
    • Other Communication Avenues
  • Contacting the Core Team
  • New Feature Planning
    • Feature changes that need a specification include:
    • What doesn’t need a design specification:
  • Task Tracking
  • Reporting a Bug
  • Getting Your Patch Merged
  • Project Team Lead Duties

Programming HowTos and Tutorials

• Proposing new features
  • Planning the feature
    • Registering a blueprint
    • Discussing the feature during the PTG
    • Writing a specification
  • Working on the implementation
    • Development environment
    • SDK and OpenStack client
    • Unit tests
    • Tempest tests
    • Documenting your work
    • Collaborative review sessions
  • Complying to the deadlines
    • Manila spec freeze
    • Manila feature proposal freeze
    • Manila new driver deadline
    • Feature freeze
  • Acceptance criteria
  • Additional tips
• Setting Up a Development Environment
  • Virtual environments
  • Linux Systems
  • Mac OS X Systems
  • Getting the code
  • Running unit tests
  • Manually installing and using the virtualenv
  • Contributing Your Work
• Setting up a development environment with devstack
  • Getting devstack
  • Sample local.conf files that get you started
    • DHSS=False (driver_handles_share_servers=False) mode:
    • DHSS=True (driver_handles_share_servers=True) mode:
    • Using a dummy back end driver
  • Building your devstack
  • More devstack customizations
    • Testing branches and changes submitted for review
    • Limiting the services enabled in your stack
    • Bootstrapping Tempest
• Running manila API with a web server
  • Installing the API via uwsgi
  • Installing the API via mod_wsgi
  • Access Control
• Unit Tests
  • Running the tests
  • Running a subset of tests
  • Database Setup
  • Gotchas
• Tempest Tests
  • Installation of plugin to tempest
  • Verifying installation
  • Configuration of manila-related tests in tempest.conf
  • Running tests
  • Running a subset of tests based on test location
  • Running a subset of tests based on service involvement
  • Running a subset of positive or negative tests
• Adding a Method to the OpenStack Manila API
  • Routing
  • Controllers and actions
  • Faults
  • Evolving the API
• Documenting your work
  • Where to add documentation?
    • OpenStack User Guide
    • OpenStack Administrator Guide
    • OpenStack Configuration Reference
    • OpenStack Installation Tutorial
    • OpenStack API Reference
    • Manila Developer Reference
    • OpenStack Security Guide
    • OpenStack Command Line Reference
  • Important things to note
• Release Notes
  • What are release notes?
  • What needs a release note?
  • What does not need a release note?
  • How do I add a release note?
  • Dos and Don’ts
  • Examples
• Using Commit Message Tags in Manila
• Guru Meditation Reports
  • Generating a GMR
  • Structure of a GMR
  • Adding Support for GMRs to New Executables
  • Extending the GMR
• User Messages
  • The Message API Module
  • The Permitted Messages Module
• Ganesha Library
  • Supported operations
  • Supported manila drivers
  • Requirements
  • NFS-Ganesha configuration
  • Further Ganesha related manila configuration
  • Using Ganesha Library in drivers
  • Customizing Ganesha exports
  • Known Restrictions
  • Known Issues
  • Deployment considerations
    • The manila.share.drivers.ganesha Module

Background Concepts for manila

• Manila System Architecture
  • Components
  • Further Challenges
• Threading model
  • Yielding the thread in long-running tasks
  • MySQL access and eventlet
• Internationalization
• AMQP and manila
  • Manila RPC Mappings
  • RPC Calls
  • RPC Casts
  • AMQP Broker Load
  • RabbitMQ Gotchas
• Manila minimum requirements and features
  • At least one driver mode (DHSS true/false)
  • At least one file system sharing protocol
  • Access rules
  • Shares
  • Share extending
  • Capabilities
  • Continuous Integration systems
  • Unit tests
  • Documentation
• Manila optional requirements and features since Mitaka
  • Snapshots
  • Managing/Unmanaging shares
  • Share shrinking
  • Share ensuring
• Manila experimental features since Mitaka
  • Share Migration
  • Share Groups (since Ocata)
  • Share Replication
  • Update “used_size” of shares
  • Share Server Migration (Since Victoria)
• Pool-Aware Scheduler Support
  • Problem Description
  • Proposed change
  • Terminology
  • Design
  • Data model impact
  • REST API impact
  • Security impact
  • Notifications impact
  • Admin impact
  • Other end user impact
  • Performance Impact
  • Developer impact
  • Documentation Impact

Other Resources

• Project hosting with Launchpad
  • Launchpad credentials
  • Mailing list
  • Bug tracking
  • Feature requests (Blueprints)
  • Technical support (Answers)
• Code Reviews with Gerrit
• Manila team code review policy
  • Peer code review and the OpenStack Way
  • Core code review guidelines
    • Trivial changes
  • Affiliation of core reviewers
  • Vendor code and review
  • References
• Manila Project Team Lead guide
  • General Responsibilities
  • Release cycle activities
  • Project Team Gathering
  • Summit
• Communicating with the manila team over IRC
  • Step 1: Register a “nick” on OFTC
  • Step 2: Register on Element
  • Step 3: Join the #openstack-manila channel
  • Step 4: Chatting across timezones

API Reference

• Manila API v2 Reference
• API Microversions
  • Background
  • When do I need a new Microversion?
  • In Code
    • Adding a new API method
    • Removing an API method
    • Changing a method’s behaviour
    • A method with only small changes between versions
    • A change in schema only
    • When not using decorators
  • Other necessary changes
  • Allocating a microversion
  • Testing Microversioned API Methods
• REST API Version History
  • 1.0 (Maximum in Kilo)
  • 2.0
  • 2.1
  • 2.2
  • 2.3
  • 2.4
  • 2.5
  • 2.6 (Maximum in Liberty)
  • 2.7
  • 2.8
  • 2.9
  • 2.10
  • 2.11
  • 2.12
  • 2.13
  • 2.14
  • 2.15 (Maximum in Mitaka)
  • 2.16
  • 2.17
  • 2.18
  • 2.19
  • 2.20
  • 2.21
  • 2.22 (Maximum in Newton)
  • 2.23
  • 2.24
  • 2.25
  • 2.26
  • 2.27
  • 2.28
  • 2.29
  • 2.30
  • 2.31
  • 2.32 (Maximum in Ocata)
  • 2.33
  • 2.34
  • 2.35
  • 2.36
  • 2.37
  • 2.38
  • 2.39
  • 2.40 (Maximum in Pike)
  • 2.41
  • 2.42 (Maximum in Queens)
  • 2.43
  • 2.44
  • 2.45
  • 2.46 (Maximum in Rocky)
  • 2.47
  • 2.48
  • 2.49 (Maximum in Stein)
  • 2.50
  • 2.51 (Maximum in Train)
  • 2.52
  • 2.53
  • 2.54
  • 2.55 (Maximum in Ussuri)
  • 2.56
  • 2.57 (Maximum in Victoria)
  • 2.58
  • 2.59
  • 2.60
  • 2.61
  • 2.62
  • 2.63 (Maximum in Wallaby)
  • 2.64
  • 2.65 (Maximum in Xena)
  • 2.66
  • 2.67
  • 2.68
  • 2.69
  • 2.70 (Maximum in Yoga)
  • 2.71
  • 2.72
  • 2.73 (Maximum in Zed)
  • 2.74
  • 2.75
  • 2.76
  • 2.77
  • 2.78 (Maximum in 2023.1/Antelope)
  • 2.79
  • 2.80
  • 2.81
  • 2.82 (Maximum in 2023.2/Bobcat)
  • 2.83
  • 2.84
  • 2.85 (Maximum in 2024.1/Caracal)
  • 2.86
  • 2.87 (Maximum in 2024.2/Dalmatian)
  • 2.88
  • 2.89 (Maximum in 2025.1/Epoxy)
  • 2.90
  • 2.91 (Maximum in 2025.2/Flamingo)
• Experimental APIs
  • Background
  • When do I need to set an API experimental?
  • When do I need to remove the experimental annotation from an API?
  • In Code

Module Reference

• Introduction to the Shared File Systems service
• Services, Managers and Drivers
  • The manila.service Module
  • The manila.manager Module
  • Implementation-Specific Drivers
• The Database Layer
  • The manila.db.api Module
  • The Sqlalchemy Driver
    • The manila.db.sqlalchemy.api Module
    • The manila.db.sqlalchemy.models Module
  • Tests
  • DB migration revisions
• Shared Filesystems
  • The manila.share.manager Module
  • The manila.share.driver Module
• Manila share driver hooks
  • Possibilities
  • Features
  • Limitations
  • Implementation in share drivers
  • What is required for writing new ‘hook’ implementation?
  • How to use ‘hook’ implementations?
  • Driver methods that are wrapped with hooks
    • The manila.share.hook.py Module
• Authentication and Authorization
  • The manila.quota Module
  • The manila.policy Module
  • System limits
• Scheduler
  • The manila.scheduler.manager Module
  • The manila.scheduler.base_handler Module
  • The manila.scheduler.host_manager Module
  • The manila.scheduler.rpcapi Module
  • The manila.scheduler.scheduler_options Module
  • The manila.scheduler.drivers.filter Module
  • The manila.scheduler.drivers.base Module
  • The manila.scheduler.drivers.chance Module
  • The manila.scheduler.drivers.simple Module
• Scheduler Filters
  • The manila.scheduler.filters.availability_zone Filter
  • The manila.scheduler.filters.base Filter
  • The manila.scheduler.filters.base_host Filter
  • The manila.scheduler.filters.capabilities Filter
  • The manila.scheduler.filters.capacity Filter
  • The manila.scheduler.filters.extra_specs_ops Filter
  • The manila.scheduler.filters.ignore_attempted_hosts Filter
  • The manila.scheduler.filters.json Filter
  • The manila.scheduler.filters.retry Filter
  • The manila.scheduler.filters.share_replication Filter
• Scheduler Weighers
  • The manila.scheduler.weighers.base Weigher
  • The manila.scheduler.weighers.base_host Weigher
  • The manila.scheduler.weighers.capacity Weigher
  • The manila.scheduler.weighers.pool Weigher
• Fake Drivers
  • The fake_compute Module
  • The fake_driver Module
  • The fake_network Module
  • The fake_utils Module
  • The fake_volume Module
• Common and Misc Libraries
  • The manila.context Module
  • The manila.exception Module
  • The manila.test Module
  • The manila.utils Module
  • The manila.wsgi Module
  • Tests
    • The test_exception Module
• Share Replication
  • Storage availability zones and replication domains
  • Replication types
  • Health of a share replica
  • Promotion
  • Snapshots
  • Access Rules
  • Understanding Replication Workflows
    • Creating a share that supports replication
    • Creating a replica
    • Deleting a replica
    • Promoting a replica
    • Resyncing a replica
    • Creating a snapshot
    • Deleting a snapshot
  • Driver Interfaces
    • Share Replica interfaces:
    • Replicated Snapshot interfaces:
• Configure and use driver filter and weighing for scheduler
  • What is driver filter and weigher and when to use it
  • Defining your own filter and goodness functions
  • Supported operations in filter and goodness functions
  • Available capabilities when creating custom functions
    • Host capabilities for a back end
    • Capabilities specific to a back end
    • Requested share capabilities
  • Extra specs for the requested share type
  • Driver filter and weigher usage examples
• Share Migration
  • Feature definition
  • API description
  • Workflows
    • Driver-assisted migration data copy phase
    • Host-assisted migration data copy phase
    • Share migration switchover phase
  • Driver interfaces
  • Additional notes
    • Share Migration driver-assisted interfaces:
    • Share Migration host-assisted interfaces:
• Share Server Migration
  • Feature definition
  • API description
  • Workflows
    • Share server migration data copy phase
    • Share server migration switchover phase
  • Driver interfaces
  • Additional notes
    • Share Server Migration interfaces:

Indices and tables

• Index

• Search Page