Waldur Documentation
Description | Documentation of an open-source marketplace platform Waldur. See the latest version at https://docs.waldur.com |
Copyright | Copyright © 2016 - 2024 Waldur team |
Table of Contents
About ↵
Getting started
Installing Waldur is a simple and straightforward process.
Pick method of installation
There are 2 supported methods:
- Using docker-compose. Fastest but runs on a single server.
- Using Helm. For deploying on Kubernetes clusters.
Configure Waldur
Tune Waldur configuration to match your deployment. Majority of the configuration is done on Mastermind side. Exact method of configuration depends on the chosen method of installation. Settings are grouped by modules, you can see all available ones in the configuration guide.
The most typical aspects for configuration are:
- Configuring identity providers. Waldur supports a range of OIDC and SAML based IdPs.
- Adding offerings for sharing among Waldur users.
Tip
For easier management of Waldur deployments and configuration we provide Ansible playbooks.
Profit
You are done! If you are happy and want to support the project, make sure you check the support page.
Danger
Before going to production, make sure you have completed the go-live checklist.
Contributing
Waldur is an open project welcoming contributions. To assure the smooth acceptance of contributions please review the contribution guidelines below.
Pull requests
We welcome contributions (patches, new features, translations, etc) through pull requests. Please make sure that the following is addressed when making a pull request:
- a request has a clear scope - new feature, bugfix, refactoring. Granular pull requests make integration much faster;
- the code is following code conventions of the corresponding platform and linters / tests are passing;
Localisation
If you see a term, which needs to be translated better, please submit a fix via Localazy.
License
All contributions to Waldur can be accepted only you agree to license your contribution under the MIT license. Please make sure that you have the right to sign off code as MIT.
Code repositories
Repository | Description |
---|---|
HomePort | Code of Waldur Homeport web interface |
MasterMind | Code of Waldur Mastermind orchestrator |
Helm package | Helm packaging of Waldur for Kubernetes |
Docker-compose | Docker-compose packaging of Waldur |
Ansible module | Ansible module for Waldur APIs |
Data processing disclaimer
Waldur developers would like to inform that we do not assume any responsibility for processing data generated or handled by the software.
Users (e.g platform operators, platform users) are solely responsible for ensuring that the data processed through our software complies with applicable laws, regulations, and industry standards. Waldur developers disclaim any liability for loss, damage, or unauthorized access to data from our software.
Our role is limited to the development of software solution. We do not control, manage, or take responsibility for our software processes' specific deployments and data, including but not limited to data storage, transmission, or any associated security measures.
Users are encouraged to implement data protection and security measures to secure their information. By using Waldur software, users acknowledge and agree that Waldur developers are not liable for any issues related to data processing.
Some highlights to keep in mind regarding user data processing in Waldur
- Platform operator should have a DPA (Data Processing Agreement) with every Service Provider connected to the platform because, in case of a service request from a Service Provider, the latter gets the ability to see members of the project whereas service is to be provisioned. For example, an HPC service gets access to project member information only when the project is requesting access to the service. The access is revoked once the service is terminated.
- Staff users (usually platform operators) can see all users personal information.
- User profile modifications are logged, including modifier network address and changes for auditing and tracing abilities. Additionally, operations connected with the user, e.g. adding or removing SSH key, are also logged.
- The authentication system is designed around the federated AAI solution, where a user is expected to conform explicitly to personal data propagation from the Identity Provider (IdP) to Waldur.
- In cases when policy allows, it is possible to create a non-personalized group or robot account to act on behalf of the user, e.g. for CICD types of workflows.
- All event logs contain references to a user - by UUID - if they are connected with the user. This allows the platform operator to have an easy information cleanup for user data according to specific deployment policies (e.g. removing data of deactivated users after two years) and to disclose user data easily collected about them.
Some suggestions to ensure that the data is securely protected
- Waldur is pretty configurable, this means that the Waldur deployment operator can configure user profiles in a way that the information requested about the users is as minimal as possible.
- User information is visible to all project members, so make sure that you include only these users in the project, who are allowed to see each other's information. In addition to that, organization managers can see the user information about users connected to that organization.
Governance
Waldur is a project co-developed by OpenNode and University of Tartu with contributions from different organizations. To make sure that the project is delivering a sound product, OpenNode maintains control over the authoritative source code and covers Product owner and Architect roles (see below).
Waldur and all of its components are released under MIT license to be as friendly towards ecosystem as possible.
Overview of the development process
Waldur team tries to maintain a transparent process of development. In a team, each person can have one or more of the roles below.
Roles
- Project manager - collects and provides requirements for a particular Waldur-based project. Multiple people can have this role.
- Product owner - analysis requirements from project managers and fits into a product roadmap. Maintains technical feature list. Single person at a time can have this role.
- Architect - oversees Waldur platform development, including backend, frontend, external tools. Has a final word on the way how components are integrated. Single person at a time can have this role.
- Developer - responsible for fulfilling tasks created. Multiple people can have this role.
Workflow
- Project manager communicates with customers, defines requirements for product owner.
- Product owner analyses requirements from all projects and creates epics for technical features implementation. Epics are assigned to the architect.
- Architect defines general development plan for features from product owner, adds description to the epic and creates separate tasks or stories for component owners.
- Developers process tasks.
- Product owner releases tagged versions of the product once a certain amount of functionality or bugfixes went in.
Publications
- 2022 - Evaluating SSH for Modern Deployments, Thomas Thaulow Stöcklin
- 2022 - Testing Estonian Scientific Computing Infrastructure Self-Service in Cypress Framework, Janeli Õun
- 2021 - A Modern CI/CD Pipeline for Cloud Native Applications, Sergei Zaiaev
- 2018 - Automated provisioning of data analytics platforms in the Estonian Scientific Computing Infrastructure, Stanislav Nazmutdinov
Reporting issues
No software is perfect and issues are to be expected. If you observe something that you think needs fixing, please provide issue report, which includes:
From HomePort:
- HAR request that has failed or that contains data required for rendering of the data.
- Screenshot of the error in a high enough resolution.
From MasterMind:
- Latest mastermind logs that include stacktrace of the error, typically core.log and celery-celery.log.
Warning
Logs may contain sensitive data, please make sure that you either cleanup the data or share it with a trusted party before sharing the actual data.
Roadmap
Warning
The roadmap page is currently deprecated. We are working towards opening up a development process to enable more transparent and up-to-date roadmap display.
Disclaimer
This document is a living document and is used for planning. Plans for the unreleased features can change without further notice and hence cannot be used as a guaranteed delivery plan, the features can be delivered both earlier and later.
Roadmap is created based on the backlog and requests from the existing users of Waldur. If you are interested in a specific topic, please reach out to us.
Some of the tasks are common and some are functional, listed below.
Continuous improvements
Documentation
There is no such thing as a perfect documentation so we are constantly working on improving it.
CI/CD
We believe that automation is a key to improving quality of code and happiness of developers, so we are constantly working on improving CI/CD related aspects.
Tests
A good software is a reliable software, so we are always trying to add more sensible tests.
Functional
The list below is based on the Epics maintained in Waldur's task manager. They are labelled with domains, which have requested them. Domains are:
- Generic - Common requirements, no extra label.
- Academia - originating from the research community;
- Commercial - originating from the commercial deployments;
- Government - originating from the public sector deployments.
Open or in progress
Code | Description | Domain |
---|---|---|
WAL-4077 | Integrate external quality metrics of Data repositories with Offerings | |
WAL-4074 | FAIR Offerings - background linking of offering PIDs with published articles | Academia |
WAL-4073 | FAIR-services - add reminders for users about referrals of consumed resources via PIDs | Academia |
WAL-4072 | Expose summaries of Offerings publicly | Academia |
WAL-4000 | Allow to limit visibility of Offering by service provider | Academia Commercial |
WAL-3999 | Support for customer credits | Academia Commercial Government |
WAL-3997 | Add common limit management support to HomePort | Academia Commercial |
WAL-3987 | Extensions to SLURM module | Academia |
WAL-3964 | Implement consolidated approach for remote user accounts management in marketplace offerings | Academia |
WAL-3963 | Make order confirmation message a common functionality for all Marketplace | Academia Government |
WAL-3951 | Implement more fine grained storage of user name | |
WAL-3943 | Shared Openstack Tenant provider phase I | Academia |
WAL-3934 | Functionality specific to deployment of Waldur in Puhuri project as Core | Academia |
WAL-3811 | Improvements to feedback collection | Government |
WAL-3805 | Direct LDAP support for Linux identity | Academia |
WAL-3793 | Tasks related to simplification of the invoice model | Government |
WAL-3788 | Add ability to see popularity of an offering from the list | |
WAL-3759 | Add support of versioning for core objects | Government |
WAL-3744 | Add support for creating / managing projects and resources through API of external Waldur | Academia |
WAL-3736 | Allow protecting resources from accidental deletion | Government |
WAL-3689 | Expose list of connected VMs for each security group | Government |
WAL-3626 | Add ability to generate API docs for select endpoints | Academia |
WAL-3625 | Migrate from Issue types to Request types for Jira support backend | Government |
WAL-3606 | Introduce Organization level service manager role | Government |
WAL-3596 | Allow logins to Rancher via keycloak | Academia Government |
WAL-3595 | Expose port management for OpenStack tenant | Government |
WAL-3589 | Expose Sankey diagram with costs and Service providers | Academia |
WAL-3585 | Rancher access group management | Academia Government |
WAL-3582 | Allow editing of invoice data for staff users | Government |
WAL-3563 | Tasks related for getting Puhuri Core to work | Academia |
WAL-3524 | Add support for sending notifications to users | Commercial |
WAL-3439 | Add support for bookmarking offerings as favourites | Academia |
WAL-3400 | Tasks related to gitlab dev pipelines | |
WAL-3339 | Offerings (Reporting) | |
WAL-3334 | Introduce vault for storing secret configuration in Waldur | |
WAL-3305 | Chart for creating overview of existing organizations | |
WAL-3285 | "Some of the services suggest purchasing of connected offerings | To Do |
WAL-3272 | Allow setting limit for the maximal size of the total volume type quota | Academia |
WAL-3218 | Payment profiles (Phase III) | |
WAL-3205 | UX stabilization (phase I) | |
WAL-3195 | Improvements to the request-based item UX | |
WAL-3136 | Marketplace Checklists (phase II) | Commercial |
WAL-3135 | Support for auto-scalability of Waldur running on K8S | |
WAL-3103 | Second phase of support for virtual routers in OpenStack. | Academia Government |
WAL-3076 | Extend current model with ability to attach VMs directly to external networks | Academia Commercial |
WAL-3072 | Support for operations on multiple objects | Commercial |
WAL-3005 | Followup tasks for payment profiles | Government |
WAL-2991 | Markeplace Scripts plugin phase I | Academia Commercial |
WAL-2965 | Enhancements to properly support virtual security gateway use-case | Government |
WAL-2961 | Tasks related to Kubernetes ON service development and operation | Government |
WAL-2922 | Tasks for exposing Offerings publicly | Academia |
WAL-2921 | Extending Organization extended payment options | Government |
WAL-2920 | Tasks related for extending Waldur with ability to assess compliancy of organizations | |
WAL-2850 | Extending Rancher to support Helm charts | Government |
WAL-2843 | Tasks related to building up monitoring for EOSC | Academia |
WAL-2780 | Integration of PID services with Waldur models | Academia |
WAL-2776 | A visual checklist for making sure that things are done for the project | Government |
WAL-2749 | Tasks connected to improving security of Waldur | |
WAL-2748 | Collection of tasks aimed at improving UX of Waldur | |
WAL-2747 | Operational tools for Waldur deployments | |
WAL-2676 | System for lightweight offering management | |
WAL-2637 | Support for creating Rancher clusters | Academia |
WAL-2623 | Introduce license support for OpenStack | Commercial |
WAL-2519 | Improvements to VMware plugin | Commercial |
WAL-2401 | Implement device booking feature | Academia |
WAL-2134 | Further developments of Marketplace | |
WAL-1442 | Enhancements to Waldur for service provider visibility | Commercial |
WAL-1309 | Implement backend and frontend support for managing JIRA as a provider and issues as resources | |
WAL-1262 | Efforts for getting Waldur into Redhat container store | |
WAL-1212 | Reanimate Zabbix plugin | |
WAL-1056 | IPv6 support for OpenStack provider | Academia Commercial Government |
WAL-868 | Refactor cost tracking | |
WAL-842 | On-demand demo environment from waldur.com | |
WAL-791 | Stress testing & Profiling (vol 1) | |
WAL-500 | Waldur-specifics for ISKE H audit | Government |
WAL-198 | Resource retention management | Academia Commercial Government |
WAL-44 | Navigation FTS | |
WAL-30 | Quick alerts |
Finished or discarded
Code | Description | Domain |
---|---|---|
WAL-3998 | Add i18n support | |
WAL-3976 | Allow setting end of life for project | |
WAL-3850 | Convert OrderItems and Invoices PDF to on-the-fly generation | |
WAL-3833 | Add an intro header to the personal dashboard | |
WAL-3804 | Slurm user list | |
WAL-3710 | Add support for tracking historical changes to important models | |
WAL-3592 | Expose measured units in invoice details | |
WAL-3587 | Render component usage as charts in homeport | |
WAL-3579 | Support for description for Secgroup Rules | |
WAL-3551 | Extensions to request-based item offerings to support Puhuri cases | |
WAL-3523 | Add regular reminders for reviewing membership data of users | |
WAL-3520 | Add a minimal privilege project member role | |
WAL-3497 | Trello integration for feature requests | |
WAL-3466 | Support editing of organizations in homeport | |
WAL-3407 | Extension of checklists to personalized ones | |
WAL-3306 | Growth chart shows changes over time of usage | Academia |
WAL-3297 | Financial overview improvements | |
WAL-3294 | Actions for setting up Waldur at VU | |
WAL-3197 | ITA PKI extension improvements | |
WAL-3096 | Add support for OpenStack Router | Academia Government |
WAL-3022 | Redesign of slurm module | |
WAL-2989 | Reports visible to support | |
WAL-2967 | Basic feature to track quality of handling of a ticket | |
WAL-2666 | Extending OpenStack integration with separate pricing for different volume types | |
WAL-2646 | Tickets related to extension of OpenStack driver | |
WAL-2596 | Drop OpenStack packages | |
WAL-2590 | Tasks related to VMware that are need additional analysis | |
WAL-2491 | VMware plugin | |
WAL-2025 | Tasks related to extension of MasterMind API for BDG SSP | |
WAL-1988 | Marketplace (3) | |
WAL-1808 | Waldur Marketplace (Phase 2) | |
WAL-1640 | Extension of ansible SDK with additional operations | |
WAL-1568 | Migrate tables to React | |
WAL-1523 | Waldur Marketplace (Phase I) | |
WAL-1504 | Implement basic support for Dutch government cloud in Waldur | |
WAL-1402 | Add support for MOAB provider | |
WAL-1289 | Add support for Jira attachments | |
WAL-1288 | Support view of users | |
WAL-1286 | Add support for LDAP-based authentication backends | |
WAL-1255 | Add support for Staff only VPC management | |
WAL-1113 | Paypal support | |
WAL-1095 | Basic Azure VM provider | |
WAL-1060 | Waldur goes to K8S | |
WAL-1058 | Resource import | |
WAL-969 | Expert provider extension | |
WAL-962 | Add organization self-registration | |
WAL-925 | Add eduGain support for authentication | |
WAL-903 | Improvements to invoice / accounting | |
WAL-839 | Miration to ES 5.x | |
WAL-834 | Migrate to Django 1.11 | |
WAL-833 | Create a PoC for Expert provider | |
WAL-832 | Ansible module for Waldur | |
WAL-793 | 2nd phase of Grafana dashboards | |
WAL-790 | Add ability to set cost limit on organization | |
WAL-751 | Support for Ansible-playbooks as application providers | |
WAL-730 | Waldur Mission Control (central management for Waldurs) | |
WAL-722 | LDAP-based SSH access provider | |
WAL-713 | Add TaaT authentication provider to Waldur | |
WAL-701 | Notifications | |
WAL-686 | Add support for smartid.ee IdP | |
WAL-604 | Basic support mode | |
WAL-597 | /admin improvements | |
WAL-596 | HomePort localization | |
WAL-595 | API Documentation | |
WAL-568 | Grafana dashbord (for operators) | |
WAL-566 | Predictive analysis for capacity planning (organization-view) | |
WAL-511 | Fixes for a broken network model | |
WAL-479 | Price estimation | |
WAL-468 | Admin and user guides (initial) | |
WAL-463 | Extended backup restoration | |
WAL-462 | Extend snapshot management | |
WAL-461 | Basic resource usage view | |
WAL-454 | R: Update django to 1.9. | |
WAL-396 | OpenStack providers pricing info | |
WAL-323 | Use neutron for network operations. | |
WAL-297 | Project policies | |
WAL-289 | Optimizer for IaaS resource selection | |
WAL-287 | Renaming of artifacts to Waldur | |
WAL-270 | OpenStack Tenant dashboard access | |
WAL-262 | OpenStack Tenant Network Management | |
WAL-259 | OpenStack Instance Access Management | |
WAL-213 | Basic policy support | |
WAL-199 | Provider details | |
WAL-197 | Customer support | |
WAL-169 | API Token management | |
WAL-168 | Extended membership management capabilities | |
WAL-106 | Refactoring: Update DRF version. | |
WAL-88 | Transactional event logs | |
WAL-82 | Controls for user profile updates | |
WAL-79 | Tenant Management | |
WAL-77 | Request-based Offerings | |
WAL-76 | Billing | |
WAL-75 | Audit log | |
WAL-68 | Waldur ServiceStore | |
WAL-43 | Waldur white-labelling | |
WAL-42 | Resource state display | |
WAL-41 | Registration | |
WAL-17 | Waldur HomePort L&F | |
WAL-15 | Waldur web page | |
WAL-9 | OpenStack VM backup management | |
WAL-8 | OpenStack Storage management | |
WAL-7 | OpenStack Instance management | |
WAL-6 | Waldur HomePort navigation | |
WAL-4 | VPC / OpenStack Tenant purchase | |
WAL-3 | Organization team management | |
WAL-2 | I want to be able to manage my SSH keys |
Screenshots
Desktop view
Login page
Organization dashboard
Project dashboard
Provider reporting and support dashboard
Call management dashboard
Marketplace
Admin dashboard
Mobile view
Login page
Organization dashboard
Project dashboard
Provider reporting and support dashboard
Marketplace
Admin dashboard
Support
Waldur is an open-source project co-developed by OpenNode and University of Tartu.
Support and sponsored development
OpenNode provides several options for support with varying SLAs.
If you would like to know more, reach out!
Managed hosting for academical institutions
Please reach out to support@hpc.ut.ee if you represent an R&D organization and interested in managed Waldur hosting.
Glossaries ↵
Glossaries
Terminology
Name | Description | Examples |
---|---|---|
Organization | Legal representation of the entity that can be a client of the Operator. | Ministry A, Department B |
Project | Functionality in Self-Service Portal, which allows to group internal resources into projects, which allows to limit access to resources for people. | Internal systems, Public web |
Service Provider | Organization can publish offerings in marketplace as soon as it is registered as service provider. | ETAIS, UT HPCC |
Offering | Service Offering from Service Provider, which can be requested via a Marketplace. Correspond to an entry in the Service Catalogue. | VPS with LB, VDC in DataCenter 1 |
Category | A grouping of the Offerings defining metadata common to all offerings in this Category. | Compute, Storage, Operations |
Section | Section is a named aggregate of offering attributes. | System information, Support, Security |
Attribute | Attribute is an atomic piece of offering metadata, it has name, type and list of options. | Peak TFlop/s, Memory per node (GB) |
Plan | An option for paying for a particular Offering. There can be multiple options but at each point in time only one Plan can be active. | Small private cloud, Big private cloud |
Order | A collection of Order items. Considered as done when all Order Items have been processed. | 3 different Offerings with configuration. |
Order Item | Connects Offering with concrete Organization and configuration settings. | Small VPC with name “test” |
Resource | Created as part of fulfilling the Order Item. Represents part of the Offering that customer Organization can use. | VM, VPC |
Category component | Specifies unit of measurement, display name and internal name of the component, which should be present in every category offerings. It is used for aggregating offering component usage and rendering dashboard charts in both project and organization workspace. | vCPU, RAM, storage |
Offering component | Usage-based component that constitute offering. It may refer to the category component via parent field in order to ensure that component usage is aggregated. | Database count, disk usage |
Plan Component | Components that constitute a plan. | vCPU, RAM, storage, network bandwidth |
Component usage | Collects reported resource usage for each plan component separately. | 5 virtual floating IPs for the last month. |
Users, Organizations and Projects
Waldur is a service for sharing resources across projects. It is based on the delegation model where an organization can allocate certain users to perform technical or non-technical actions in the projects.
The most common types of Waldur installations include:
- Cloud - used in commercial or government sectors for providing access to cloud resources like virtual machines, storage and Kubernetes clusters.
- Academic - used in research and education. Waldur is deployed for a single university, high school or research infrastructure.
- Academic Shared - the same purpose as Academic, but is shared among several universities or infrastructures.
Glossary
User
An account in Waldur belonging to a person or a robot. A user can have roles in Organizations and Projects. Some users - mostly affiliated with Waldur operator - can have global roles, e.g. support or staff.
Organization
A company or a department. Organization can be a customer, a service provider or both.
A faculty, department or an institute. Organization can be also a service provider, for example, an HPC center.
In Academic Shared model, all organizations are service providers allocating resources to their users (research groups or classes) through their Projects.
Project
A project within an Organization. Used for organizing and isolating Resources and Users.
Service Provider
Organization that provides services to other organizations.
User types
User | Support agent | Staff | |
---|---|---|---|
Web and API access | |||
Can create support requests | |||
Can provide user support | |||
Can see all projects and resources | |||
Can manage organizations | |||
Can access admin area |
User roles in Organization
Owner | Service Manager | Project Manager | System Administrator | |
---|---|---|---|---|
Manage Team | (pre-approved users) | |||
Manage Projects | ||||
Request and Manage Resources | ||||
Approves creation of Resource Requests (Orders) | (configurable) | |||
Approves Resource Requests (Orders) | ||||
Manage Offerings (Service provider-specific) |
PI | Service Manager | co-PI | Member | |
---|---|---|---|---|
Manage Team | (pre-approved users) | |||
Manage Projects | ||||
Request and Manage Resources | ||||
Approves creation of Resource Requests (Orders) | (configurable) | |||
Approves Resource Requests (Orders) | ||||
Manage Offerings (Service provider-specific) |
Resource allocator | Service Manager | PI | co-PI | Member | |
---|---|---|---|---|---|
Manage Team | (pre-approved users) | ||||
Manage Projects | |||||
Request and Manage Resources | |||||
Approves creation of Resource Requests (Orders) | (configurable) | ||||
Approves Resource Requests (Orders) | |||||
Manage Offerings (Service provider-specific) |
Ended: Glossaries
Changelog
7.0.5
Notes: Bugfix release
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Thu Oct 17 19:44:16 UTC 2024
7.0.3
Notes: Expose set usage action in provider resource view
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Sun Oct 13 10:51:03 UTC 2024
7.0.2
Notes: Initial version of migration
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Fri Oct 11 20:32:54 UTC 2024
7.0.1
Notes: Bugfix release
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Wed Oct 9 21:28:21 UTC 2024
7.0.0
Notes: Bugfix release
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Tue Oct 1 19:48:59 UTC 2024
6.9.9
Notes: None
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Sun Sep 29 08:20:55 UTC 2024
6.9.8
Notes: Bugfixes
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Tue Sep 17 21:37:59 UTC 2024
6.9.7
Notes: Improved username display in team tabs, bugfixes.
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Fri Sep 13 14:15:32 UTC 2024
6.9.6
Notes: Openstack bugfixes
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Wed Sep 11 18:38:37 UTC 2024
6.9.5
Notes: Bugfix release
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Wed Sep 11 10:11:47 UTC 2024
6.9.4
Notes: Fix initialization of resource options
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Tue Sep 10 07:29:29 UTC 2024
6.9.3
Notes: Fix docker executor issue due to a conflict with requests
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Mon Sep 9 11:25:59 UTC 2024
6.9.2
Notes: Bugfixes, start of merging of Openstack applications.
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Thu Sep 5 13:40:32 UTC 2024
6.9.1
Notes: Bugfix release
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Tue Aug 27 10:37:35 UTC 2024
6.9.0
Notes: Resource option update bugfix
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Sun Aug 25 20:35:08 UTC 2024
6.8.9
Notes: Bugfixes
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Fri Aug 23 17:49:29 UTC 2024
6.8.8
Notes: None
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Wed Aug 21 19:47:22 UTC 2024
6.8.7
Notes: Allow exposing external IPs for Openstack deployments
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Sat Aug 17 08:00:05 UTC 2024
6.8.6
Notes: Bugfixes
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Thu Aug 15 16:25:26 UTC 2024
6.8.5
Notes: Extended user-onboarding options
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Wed Aug 14 10:10:26 UTC 2024
6.8.4
Notes: User management UI improvements
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Sun Aug 11 19:44:26 UTC 2024
6.8.3
Notes: Bugfix
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Thu Aug 8 09:41:55 UTC 2024
6.8.2
Notes: Introduce new configuration method in HomePort
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Wed Aug 7 11:01:56 UTC 2024
6.8.1
Notes: Fix resource name suggestion button
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Thu Aug 1 19:14:05 UTC 2024
6.8.0
Notes: Bugfixes
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Wed Jul 31 18:44:21 UTC 2024
6.7.9
Notes:
- Add slugs for main objects
-
Bugfixes
-
Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Thu Jul 25 08:33:49 UTC 2024
6.7.8
Notes:
- Bugfix
-
Extended SSH key hashes with sha256 and sha512
-
Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Sun Jul 21 18:05:27 UTC 2024
6.7.7
Notes: Bugfix
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Sun Jul 14 20:31:27 UTC 2024
6.7.6
Notes: Fix support configuration loading
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Thu Jul 11 15:01:09 UTC 2024
6.7.5
Notes: Bugfix
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Thu Jul 11 10:44:33 UTC 2024
6.7.4
Notes: Bugfixes
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Mon Jul 8 15:26:54 UTC 2024
6.7.3
Notes: Fixes broken 6.7.2 release
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Mon Jul 1 14:12:05 UTC 2024
6.7.2
Notes: None
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Sun Jun 30 19:51:44 UTC 2024
6.7.1
Notes: Bugfix release
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Fri Jun 21 21:40:08 UTC 2024
6.7.0
Notes: Introducing renewed UI
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Mon Jun 17 15:42:36 UTC 2024
6.6.9
Notes: None
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Tue Apr 30 07:40:46 UTC 2024
6.6.8
Notes: Bugfixes.
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Mon Apr 29 08:54:03 UTC 2024
6.6.7
Notes: Bugfixes
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Fri Apr 26 15:11:26 UTC 2024
6.6.6
Notes: Fix user management permissions.
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Mon Apr 22 16:07:21 UTC 2024
6.6.5
Notes: None
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Fri Apr 19 11:05:01 UTC 2024
6.6.4
Notes: Volume type selector bugfix
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Sun Apr 7 08:45:51 UTC 2024
6.6.3
Notes: Add support for Matomo user tracking
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Thu Apr 4 17:29:13 UTC 2024
6.6.2
Notes: Bugfix release
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Wed Apr 3 09:04:26 UTC 2024
6.6.1
Notes: Bugfix
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Mon Apr 1 15:40:22 UTC 2024
6.6.0
Notes: None
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Mon Apr 1 13:43:17 UTC 2024
6.5.9
Notes: SMAX configuration bugfix
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Tue Mar 26 21:45:17 UTC 2024
6.5.8
Notes: Bugfixes
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Tue Mar 26 19:20:27 UTC 2024
6.5.7
Notes: Bugfixes
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Mon Mar 25 17:45:10 UTC 2024
6.5.6
Notes: Bugfix release
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Fri Mar 15 20:08:05 UTC 2024
6.5.5
Notes: Openstack caching bugfix
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Tue Mar 12 19:31:25 UTC 2024
6.5.4
Notes: Bugfix
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Mon Mar 11 20:22:24 UTC 2024
6.5.3
Notes: Bugfix
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Thu Mar 7 18:23:33 UTC 2024
6.5.2
Notes: None
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Tue Mar 5 21:29:54 UTC 2024
6.5.1
Notes: Bugfix
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Tue Feb 27 20:45:36 UTC 2024
6.5.0
Notes: Bugfix release
- Waldur Mastermind: tag diff
- Waldur Homeport: tag diff
- Waldur Helm: tag diff
- Waldur Docker Compose: tag diff
- Waldur Prometheus Exporter: tag diff
Date: Mon Feb 26 22:29:21 UTC 2024
Ended: About
Admin guide ↵
Architecture
Waldur is composed of a several components.
- Homeport (web client, graphical interface) - React application
- Mastermind API server - Django/Django REST Framework application implementing the core business logic
- Celery workers - Background processing of tasks
- Celery beat - Scheduling of periodic tasks for background processing
- PostgreSQL database - Storing persistent data, also serves as Celery result store in Kubernetes deployment
- Redis - Tasks queue and result store for Celery (Docker Compose deployment only)
- RabbitMQ - Tasks queue and result store for Celery (Kubernetes deployment only)
Backups
Waldur keeps state in 2 components:
- Database - main persistency layer.
- Message queue - contains transient data mostly about scheduled jobs and cache.
Of these, only database needs to be backed up.
A typical approach to a backup is:
1. Create a DB dump
- An entire db dump
1 |
|
- An entire db dump with cleanup commands:
1 |
|
- A db dump containing only data
1 |
|
2. Copy backup to a remote location
Using rsync / scp or more specialised tools.
3. Restore the created backup
1 |
|
We suggest to make sure that backups are running regularly, e.g. using cron.
Billing and accounting in Waldur
Waldur's accounting and billing components are responsible for collecting accounting data and presenting it to end users. It features built-in reporting and accounting functionality, enabling the tracking of usage information for each project and its resources. During the service offering creation process, providers can define accounting components (such as CPU-h, GPU-h, and storage for HPC; CPU, RAM, and storage for VMs) and set the pricing plans for each component. Consumers can view usage information according to the policies established by the provider.
From a provider point of view, Waldur supports invoice generation and exposes enough of information via APIs to integrate with custom payment providers.
Waldur offers convenient tools for consumers to view resource usage information. The user interface displays overall usage data within a project and breaks down monthly usage across resource components such as CPU, GPU, and storage. End users can export this usage data in PDF, CSV, and XLSX formats. Access to information varies by user role: project members can see details for their specific projects, while organization owners can view information for all projects within their organization.
In addition to that, Waldur offers convenient way for exporting the usage information for visualization with Grafana.
Checklist for Go live
General
- Make sure that privacy policy and terms of use are updated to the site specific ones.
- Make sure that SMTP server and outgoing email address are configured and emails are sent out.
- Reboot test: restart all the nodes where Waldur components are running, application should recover automatically.
Security
- Remove or disable default staff accounts.
- Generate a new random secret key.
Backups
- Make sure that configuration of Waldur is backed up and versioned.
- Assure that DB backups are performed, i.e. backups are created when manually triggering
- Assure that DB backups files are on a persistent storage, preferably outside the storage used for Waldur's database.
Air-gapped deployments
- Make sure that Waldur docker images are mirrored to a local registry.
Cookie policy and Telemetry
Cookie policy
Waldur can save data about the user in a browser. Data type and policy depends on the component.
HomePort
- Saving of the latest view point of the user.
- Saving redirect information, i.e. where to forward from a certain state.
- Saving which authentication method was used by user for logging in.
- Saving user session token.
- Saving user language preference.
MasterMind
- Saving authentication token (cookie) when a user logs into /admin management interface.
Telemetry
Waldur can send telemetry metrics to the telemetry server. Metrics are sent only if the feature is enabled and the telemetry server is configured in the Waldur settings.
To toggle the feature on or off, navigate to Administration -> Settings -> Features
in HomePort and enable or disable the Send telemetry metrics
feature.
An example of telemetry metrics is shown below:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
|
Debug instructions for Waldur Mastermind
Filter logs for email-related events
Upon sending an email, Waldur logs an event to the Celery output.
Docker Compose
A dedicated container logger
collects all the logs from other Waldur containers.
All you need is to:
-
Go to the logs directory. It should be in the same directory where Compose runs:
1 2 3
$ cd ./logs $ ls -lh waldur-mastermind-worker.log -rw-r--r--. 1 root root 39M Jun 3 08:53 waldur-mastermind-worker.log
-
Check the logs in the corresponding file:
1 2 3 4 5 6 7
$ cat waldur-mastermind-worker.log | grep -i "about to send" ... [2024-05-31 08:09:46,569: INFO/ForkPoolWorker-1] About to send notify_provider_about_pending_order notification to email1@example.com [2024-05-31 08:09:48,706: INFO/ForkPoolWorker-1] About to send notify_provider_about_pending_order notification to email2@example.com [2024-05-31 08:09:49,524: INFO/ForkPoolWorker-8] About to send notify_provider_about_pending_order notification to email3@example.com [2024-05-31 09:17:05,673: INFO/ForkPoolWorker-8] About to send invitation_created notification to email1@example.com [2024-05-31 09:56:55,144: INFO/ForkPoolWorker-8] About to send notify_provider_about_pending_order notification to email2@example.com
Helm
In this case, you can use the same approach, but execute kubectl
instead of docker
command:
1 |
|
Grafana and Prometheus Metrics
Waldur Homeport includes a number of reports, but for cases when additional custom reports need to be created, it is possible to setup a time-series database, for example, Prometheus, and setup business metrics exporter for Waldur.
This would allow to create live dashboards exposing, for example, growth of adoption of the platform in terms of users and offerings, aggregated costs of resource on a daily or weekly basis, total active provisioned resources on an hourly basis and so on.
To achieve that, waldur-prometheus-exporter needs to be setup. In addition, we provide example Grafana dashboard json for visualising the metrics.
Prometheus metrics
Prometheus exporter allows to setup export of business metrics and reporting information at the fine-grained granularity, for example, every 5 minutes or daily. Collected information can then be visualized in Grafana or other visualisation solutions.
Currently, the following metrics are supported:
- Total count of users;
- Total count of organizations;
- Total count of projects;
- Total count of users with owner permissions;
- Total count of support users;
- Total count of users with local registration method;
- Total count of users with saml2 registration method;
- Total count of users with tara registration method;
- Total count of users with eduteams registration method;
- Total count of active resources;
- Count of projects for each organization;
- Count of resources for every organization;
- Count of members for every organization;
- Resources limits by offerings, customer groups, customer countries;
- Aggregated usages by offerings, customer groups, customer countries;
- Aggregated usages per month;
- Count of users visible to service provider;
- Count of projects visible to service provider;
- Count of projects visible to service provider and grouped by OECD science code;
- Total cost of active resources per offering;
- Projects usages grouped by OECD science code;
- Projects limits grouped by OECD science code;
- Projects usages grouped by industry flag;
- Projects limits grouped by industry flag;
- Count unique users connected with active resources of a service provider;
- Count active resources grouped by offering;
- Count active resources grouped by country;
- Count active resources grouped by organization group;
- Count projects with active resources grouped by provider and OECD science code;
- Count projects with active resources grouped by provider and industry flag.
Hardware requirements
Docker-compose deployment (on a single server)
- Docker version: 1.13+
- Minimal configuration: 4 vCPU, 12 GB RAM
Helm-based deployment
- Kubernetes version: 1.18+
- Minimal namespace limits:
- CPU: 8000m
- Waldur: 4000m
- PostgreSQL: 4000m
- RAM: 10000Mi
- Waldur: 6000Mi
- PostgreSQL: 4000Mi
- Storage: 20Gi (PostgreSQL DB)
- Recommended namespace limits:
- CPU: 12000m
- Waldur: 6000m
- PostgreSQL: 6000m
- RAM: 14000Mi
- Waldur: 8000Mi
- PostgreSQL: 6000Mi
- Storage: 40Gi (PostgreSQL DB)
Component specific requirements
Waldur Mastermind (API)
By default 4 uWSGI processes are started.
- Minimum requirements: 1 CPU, 1GB RAM for every node
- Recommended setup: 2 CPU or more, 2 GB RAM or more
Waldur Mastermind (Celery worker)
By default a single worker with 10 threads is started.
- Minimum requirements: 2 CPU, 1 GB RAM
- Recommended setup: 4 CPU or more, 8 GB RAM or more
More memory should be added if more Celery worker processes are running on the same host (512 MB for each 4 Celery workers).
Waldur Mastermind (Celery beat)
A single Celery beat process is started.
- Minimum and recommended requirements: 1 CPU, 1 GB RAM
PostgreSQL
- Minimum requirements: 1 CPU, 1 GB RAM
- Recommended setup: 2 CPU or more, 2 GB RAM or more
Redis
- Minimum requirements: 1 CPU, 512 MB RAM
- Recommended setup: 2 CPU or more, 1 GB RAM or more
Waldur HomePort (Nginx)
- Minimum and recommended requirements: 1 CPU and 512MB RAM
Managing Waldur with Ansible
NB! Repository with Ansible playbooks for Waldur management is not open-sourced. It is available to Waldur users that have purchased support packages.
Compatibility
Ansible version 2.9 is supported; code in this repository may work with other Ansible versions but it is not guaranteed.
Quick setup
- Make sure that you have:
- Folder containing managed-ansible Ansible installer (this one).
- Folder containing deployment-specific settings.
- Copy
setup_deployment.sh.example
tosetup_deployment.sh
, adjust:- INSTALLER_PATH - full path to current folder
- DEPLOYMENT_CONFIG_PATH - full path to folder with deployment-specific information
- DEPLOYMENT_IDS - list of deployment IDs you want to manage.
- Run ./setup_deployment.sh. This will create required symlinks.
- Run
ansible-playbook -DC <deployment_id.yml>
to check what installer will do. - Run
ansible-playbook -D <deployment_id.yml>
to apply the installer.
Upgrading installer
- Download a new archive into a separate folder and unpack.
-
Check what has changed:
rsync --dry-run -avzh unpacked-folder-eg-ansible-3.2.3/ /path/to/installer/
-
Do the upgrade:
rsync -avzh unpacked-folder-eg-ansible-3.2.3/ /path/to/installer/
Upgrading Waldur
Upgrading Waldur to a new version is achieved by following the checklist:
- Update deployment-specific variables for the new version in
groups_vars/<deployment_id>/vars
andgroups_vars/<deployment_id>/vault
(if setting is private). - Update target version in
groups_vars/<deployment_id>/vars
: setwaldur_homeport_version
andwaldur_mastermind_version
to a new version of the Waldur release. - Run
ansible-playbook -DC <deployment_id.yml>
to check what installer will do during the upgrade. - Run
ansible-playbook -D <deployment_id.yml>
to perform an upgrade.
Add new deployment
Infrastructure:
- Prepare servers matching requirements.
- Make sure you can access them by SSH by running only
ssh <host>
. Otherwise you should tweak~/.ssh/config
file or describe connectivity in the Ansible inventory.
Ansible (this repository):
- Add new deployment-specific host group to
hosts
file (example:[foo]
); add hosts to this group. - Add hosts to Waldur role groups in
hosts
file. - Add variable files for new deployment:
group_vars/foo/vars
andgroup_vars/foo/vault
- Add deployment specific information under
deployments
folder. - Copy existing playbook that is the closest match for a new deployment; modify as needed
- Run Ansible playbook to set up deployment:
ansible-playbook -D foo.yml
Remove deployment
Ansible (this repository):
- Delete deployment-specific playbook, roles, tasks, templates etc.
- Delete variable files:
rm -rf group_vars/foo
- Delete deployment-specific host group and all deployment-specific hosts from
hosts
file (example:[foo]
)
Managing Waldur deployed as Helm
Requirements:
- Installed and running
kubernetes
system on a node (e. g. minikube) - Installed
kubectl
on the node
Place all configuration files for release in next manner:
values.yaml
->roles/waldur_helm/files/waldur_helm/waldur/
values.yaml
->roles/waldur_helm/files/waldur_helm/waldur/
- Files related to TLS ->
deployments/<deployment_id>/tls/
- Files related to white-labeling ->
deployments/<deployment_id>/whitelabeling/
- Files related to mastermind templates ->
deployments/<deployment_id>/mastermind_templates/
- Files related to stress testing ->
deployments/<deployment_id>/locust_tasks/
- Files related to SAML2 ->
deployments/<deployment_id>/waldur_saml2/
More configuration info:
Multilingual User Interface
Waldur user interface is available in several languages. Default language is English, but the end users may have several other options to choose from. The number of available languages depends on the Waldur's configuration. Current status of the overall avalable languages are visible on the Localazy website.
Waldur uses Localazy service, to translate the user interface. Localazy is a continuous localization platform and web-based translation management system. This allows to use AI or human translation. Everyone can contribute to Waldur's translation by adding new translantions or fixing current ones, more information here.
OfferingUser management
OfferingUser is a model in Waldur, which represents a link between an offering available in marketplace and a user. A service provider can utilize it to create an account for a service visible for all the offering resources, for example: a user account in a SLURM cluster. As an account, an OfferingUser can have a custom username different from user's one.
This feature is available for offerings of types:
- Basic
- SLURM
- SLURM remote
- Custom script
- Rancher
For Basic, SLURM remote and Custom script offerings, offering-users are created automatically when a user is added to the project with active offering resources or when a new offering resource is created.
In case of Rancher, offering-users are created when users are imported from a Rancher cluster.
In case of SLURM, offering-users are created when association are imported from a SLURM cluster.
Username generation
The username
field for the model can be generated via strategies:
service_provider
: a service provider should manually set usernames for the offering users (default strategy);anonymized
: usernames are generated with<prefix>_<number>
, e.g. "anonym_00001"; the prefix must be specified in the plugin options of the offering asusername_anonymized_prefix
;full_name
: usernames are constructed using first and last name of users with numerical suffix, e.g. "john_doe_01";waldur_username
: uses a username of a user;freeipa
: uses the username field of a corresponding FreeIPA profile.
A service provider can choose the policy via UI:
- go to offering edit section in a service provider page;
- open
Integration
tab; - click
Edit integration options
; - choose a username generation policy from the drop-down list;
- click
Save
button.
After this, the usernames are regenerated for all the linked offering users.
Waldur Shell
Waldur provides a shell for command line scripting. To start a shell, run waldur shell
in the MasterMind context.
For docker-compose deployments, please run:
docker exec -it waldur-mastermind-api waldur shell
For Helm-based K8s deployments, please run:
1 2 3 |
|
Examples
Setting/removing staff permissions for a user
1 2 3 4 5 6 7 8 |
|
Creating a new user with token only authentication
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
|
Triggering pulling of usage data from remote Waldur
1 2 3 |
|
Apply changes in Waldur HPC plugin to existing users
1 2 3 4 5 |
|
Cleanup leftover ports from OpenStack Project
Lookup UUID of an OpenStack tenant (aka backend_id in Waldur).
1 2 3 4 5 6 7 8 9 10 11 12 |
|
Add affiliations to user
1 2 3 4 5 |
|
Create a service user for API access
To create a service user - without valid access credntials and non-expiring Token, please run the following script.
1 2 3 4 5 6 7 8 9 10 11 |
|
Synchronise SLURM associations
Note: <allocation-uuid>
field can be found in an allocations's details page.
Select Organization -> Select project -> Select allocation -> Find 'UUID' field in the page.
1 2 3 4 5 6 7 8 |
|
Lookup user details from Eduteams
Note: USER_CUID
is a unique ID of user in Eduteams.
1 2 3 4 5 |
|
Generate report for list of projects and their details
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
|
Generate report for OpenStack resources across projects
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 |
|
Update limits for all tenants in a specific organization
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
|
Generate cost report for a specific organization by month
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
|
Generate a report for VMs created within a specific tenant offering
Upon running the script, please change year
and offering_uuid
variables.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 |
|
Migrate users to a new Keycloak instance
Introduction
There are 3 scripts involved:
-
export-keycloak-user-permissions.py: exports Keycloak user data to a
.yaml
file in the following format:1 2 3 4 5 6 7 8 9 10 11 12 13 14
- username: johndoe email: johndoe@example.com full_name: John Doe permissions: - type: project project_uuid: bed45d99e83d4c17a5bf5908ad70554e role_uuid: e4130fde02474571a5166bb6742dc2d0 project_name: "Project 01" role_name: "PROJECT.MANAGER" - type: customer customer_uuid: 1aaec6489ea7492cbe0401997de13653 role_uuid: 16ec8cf8874d467d9a2c7a0c822c6b3e customer_name: "Organization 01" role_name: "CUSTOMER.OWNER"
-
delete-keycloak-users.py: removes data about all the users from an old Keycloak instance
-
invite-keycloak-users.py: creates and sends invitations to the user emails based on their roles in project and organizations
When you are ready to migrate users to the new Keyaloak instance:
- copy the script file to the
waldur-mastermind-api
container usingdocker cp
orkubectl cp
commands; - connect to the container shell using
docker exec
orkubectl exec
; - execute the scripts sequentially using
waldur shell
:
1 2 3 |
|
export-keycloak-user-permissions
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 |
|
delete-keycloak-users
1 2 3 4 |
|
invite-keycloak-users
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 |
|
White-labeling instructions
To change white-labeling settings on the fly, you can perform following steps:
-
Go to admin panel (e.g.
http://localhost:8080/admin/
) -
Open Templates:
Utilities
->Constance
->Config
You will see a list of white-labeling settings available to be changed.
You can change them as you wish to, or you can reset them to default values.
Save the changes and you are good to go.
Deployment ↵
Waldur Docker-compose deployment
Prerequisites
- at least 8GB RAM on Docker Host to run all containers
- Docker v1.13+
Prepare environment
1 2 3 4 5 |
|
Booting up
1 2 3 4 5 6 7 8 9 10 11 12 |
|
Waldur HomePort will be accessible on https://localhost. API will listen on https://localhost/api.
Healthcheck can be accessed on https://localhost/health-check.
Tearing down and cleaning up:
1 |
|
Logs
Logs emitted by the containers are collected and saved in the waldur_logs
folder. You can change the location by
editing environment variable (.env
) and updating LOG_FOLDER
value.
Known issues
When Waldur is launched for the first time, it applies initial database migrations. It means that you may need to wait few minutes until these migrations are applied. Otherwise you may observe HTTP error 500 rendered by REST API server. This issue would be resolved after upgrade to Docker Compose 1.29.
To use a custom script offering type, it should be possible to connect to /var/run/docker.sock
from
within the Waldur containers. If you are getting a permission denied error in logs, try setting more
open permissions, for example, chmod 666 /var/run/docker.sock
. Note that this is not a secure
setup, so make sure you understand what you are doing.
Upgrading Waldur
1 2 |
|
Using TLS
This setup supports following types of SSL certificates:
- Email - set environment variable TLS to your email to register Let's Encrypt account and get free automatic SSL certificates.
Example:
1 |
|
- Internal - set environment variable TLS to "internal" to generate self-signed certificates for dev environments
Example:
1 |
|
- Custom - set environment variable TLS to "cert.pem key.pem" where cert.pem and key.pem - are paths to your custom certificates (this needs modifying docker-compose with path to your certificates passed as volumes)
Example:
1 |
|
Custom Caddy configuration files
To add additional caddy config snippets into the caddy virtual host configuration add .conf files to config/caddy-includes/
Keycloak
Keycloak is an Identity and Access Management software bundled with waldur-docker-compose.
To create a keycloak admin account set KEYCLOAK_ADMIN
env variable in docker-compose.yaml
and KEYCLOAK_ADMIN_PASSWORD
in .env
file.
After this, you can login to the admin interface at https://localhost/auth/admin and create Waldur users.
To use Keycloak as an identity provider within Waldur, follow the instruction here. The discovery url to connect to Keycloak from the waldur-mastermind-api container is:
1 |
|
Integration with SLURM
The integration is described here.
Whitelabeling settings
To set up whitelabeling, you need to define settings in ./config/waldur-mastermind/whitelabeling.yaml
.
You can see the list of all whitelabeling options below.
General whitelabeling settings
- site_name
- site_address
- site_email
- site_phone
- short_page_title
- full_page_title
- brand_color
- brand_label_color
- hero_link_label
- hero_link_url
- site_description
- currency_name
- docs_url
- support_portal_url
Logos and images of whitelabeling
The path to a logo is constructed like so: /etc/waldur/icons - is a path in the container (Keep it like it is) + the name of the logo file from config/whitelabeling directory.
All-together /etc/waldur/icons/file_name_from_whitelabeling_directory
- powered_by_logo
- hero_image
- sidebar_logo
- sidebar_logo_mobile
- site_logo
- login_logo
- favicon
Argocd ↵
Waldur deployment in ArgoCD
This repository contains ansible playbook settings for infrastructure setup (ansible/
directory)
together with Kubernetes manifest files for different applications managed by ArgoCD (applications/
directory).
Infrastructure setup
Before beginning with application management, infrastructure setup is required. For this, you should use the playbook ansible/cloud-infrastructure-setup.yaml. Given an access to virtual machines with python3.8+ installed, it is capable of:
- Disk setup in case if each virtual machine has a separate disk attached as a device;
- Installation of RKE2-managed Kubernetes cluster with a single server and workers;
- Installation of Helm tool binary;
- Installation of ArgoCD: both Kubernetes manifests and command-line binary.
All these steps can be customized via either ansible/vars.defaults or ansible/vars.custom
file.
The example infra has 3 VMs with python3.9
installed.
After establishing ssh-based connection to the machines, you can execute the playbook:
1 |
|
After successful run, the infra is ready for further steps.
Installation and management of applications
You should run all the command described below on the RKE2 server, where ArgoCD binary installed, only.
Prerequisite
The following lines ensure user login to ArgoCD server via argocd
binary.
They should run prior to every application-related action.
1 2 3 |
|
You can validate authentication and access:
1 2 |
|
Longhorn
You can use this app manifest and this custom values file for Longhorn installation.
This script creates a new Kubernetes namespace, where application is created synched:
1 2 3 |
|
PostgreSQL operator
You can use this app manifest and this custom values file for PostgreSQL operator installation.
This script creates a new Kubernetes namespace, where application is created synched:
1 2 3 |
|
Waldur
Waldur requires PostgreSQL database as a persistent storage and RabbitMQ as a message queue to be up and running.
Firstly, you need to create a namespace for Waldur:
1 |
|
Secondly, create and sync PostgreSQL application managed by the operator installed before. You can use this manifest for ArgoCD app and this manifest for modification of the DB settings.
1 2 |
|
Finally, you can deploy Waldur using this app manifest and these values. NB: RabbitMQ is included in the deployment.
1 2 |
|
Ended: Argocd
Helm ↵
Waldur Helm
Waldur is a platform for creating hybrid cloud solutions. It allows building enterprise-grade systems and providing self-service environment for the end-users.
Introduction
This chart bootstraps a Waldur deployment on a Kubernetes cluster using the Helm package manager.
Installing prerequisites
- Install Kubernetes server, for example, using minikube
- Install Kubernetes client, i.e. kubectl
- Install Helm
Installing the chart
-
Add the Waldur Helm repository
1
helm repo add waldur-charts https://waldur.github.io/waldur-helm/
-
Install dependencies or enable them in Helm values
Setup database using one of: - Simple PostgreSQL DB: instructions or - PostgreSQL HA DB: instructions or - Integrate with external DB: instructions
Install MinIO (for database backups): instructions
Install RabbitMQ for task queue: instructions
-
Install the Helm chart
1
helm install my-waldur waldur-charts/waldur -f path/to/values.yml
NB After this command, Waldur release will run in default
namespace.
Please, pay attention in which namespace which release is running.
For instance, you can install Waldur release
in test
namespace in the following way:
-
Create
test
namespace:1
kubectl create namespace test
-
Install release:
1
helm install waldur waldur --namespace test
However, postgresql release and waldur should be installed in the same namespace in order to share a common secret with DB credentials.
Adding admin user
Open waldur-mastermind-worker shell and execute the following command:
-
Get waldur-mastermind-worker pod name
1 2 3
# Example: kubectl get pods -A | grep waldur-mastermind-worker # --> # default waldur-mastermind-worker-6d98cd98bd-wps8n 1/1 Running 0 9m9s
-
Connect to pod via shell
1 2
# Example: kubectl exec -it deployment/waldur-mastermind-worker -- /bin/bash
-
Execute command to add admin user
1
waldur createstaffuser -u user -p password -e admin@example.com
Waldur Helm chart release upgrading
Delete init-whitelabeling job (if exists):
1 |
|
Delete load features job (if exists):
1 |
|
Upgrade Waldur dependencies and release:
1 2 |
|
Restart deployments to apply configmaps changes:
1 2 3 4 |
|
Private registry setup
A user can use private registry for Docker images.
For this, the corresponding credentials should be registered in a secret,
name of which should be placed in .Values.imagePullSecrets
.
A secret can be created trough CLI.
Configuration docs
Configuration documentation: index
Docs ↵
Waldur Helm chart configuration
Outline:
Bootstrap configuration
You can create a bootstrapping script and Helm will run it right after Waldur release installation.
Example script:
1 2 3 4 5 6 7 8 |
|
This script with all necessary additional files
should be placed in bootstrap.dir
directory.
Additional configuration variables (bootstrap
prefix):
enabled
- enable/disable bootstrapscript
- main script file inbootstrap.dir
folder.dir
- directory with all bootstrap files
Moreover, that is better to install release with --wait
flag:
1 |
|
This allows running migrations job before a bootstrap one.
more info: link,
Hooks and the Release Lifecycle
section)
NB:
-
A script, which contains interaction with a db can fail due to not all migrations are applied. Automatical reruning of the bootstrap job is normal behaviour in such situations.
-
Hence, the script should be idempotent.
External DB integration
Waldur Helm can use an external PostgreSQL deployed within the same Kubernetes cluster.
For this, you need to set the following variables in values.yaml
:
externalDB.enabled
- toggler for integration; requirespostgresql.enabled
andpostgresqlha.enabled
to befalse
externalDB.flavor
- a type of the DB management system; currently onlyzalando
(Zalando operator) is supportedexternalDB.secretName
- name of the secret with PostgreSQL credentials for Waldur user; should includeusername
andpassword
keysexternalDB.serviceName
- name of the service linked to PostgreSQL master
Zalando-managed PostgreSQL cluster example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
|
Backup setup
Enable backups for a cluster with the following addition to a manifest file:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 |
|
You also need to create a secret file with the credentials for the storage:
1 2 3 4 5 6 7 8 9 10 11 |
|
Trigger a base backup manually
Connect to the leader PSQL pod and execute the following commands:
1 2 3 4 5 6 7 8 9 10 |
|
Restore DB from backup
The preferable option is creation a new instance of PostgreSQL cluster cloning data from the original one.
For this, create a manifest with the following content:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 |
|
Then, apply the manifest to the cluster, change externalDB.{secretName, serviceName}
after DB bootstrap and upgrade Waldur release.
Official documentation
Documentation of installation link: Helm
Installing Helm
- Download and install Helm
1 2 3 |
|
- Check the version
1 |
|
Host aliasing
You can specify additional hosts for Waldur containers in the same manner as the /etc/hosts
file using host aliasing. To create aliases, a user needs to modify the hostAliases
variable in waldur/values.yaml
file. Example:
1 2 3 4 |
|
This will add a record for my.host.example.com
to the /etc/hosts
file of all the Waldur containers
HPA setup and configuration
It is possible to use cpu-utilization-based HPA
for API server (aka waldur-mastermind-api) and
Celery executor (aka waldur-mastermind-worker
and waldur-mastermind-beat
) pods.
Setup
If you use minikube, you need to enable metrics-server
using next command:
minikube addons enable metrics-server
Configuration
In values.yaml
file you can configure HPA for:
-
API server (
hpa.api
prefix):1.1
enabled
- flag for enabling HPA. Possible values:true
for enabling andfalse
for disabling.1.2
resources
- custom resources for server.requests.cpu
param is mandatory for proper HPA work.1.3
cpuUtilizationBorder
- border percentage of average CPU utilization per pod for deployment. -
Celery (
hpa.celery
prefix):2.1
enabled
- flag for enabling HPA, the same possible values as for API server.2.2
workerResources
- custom resources for celery worker.requests.cpu
param is mandatory for proper HPA work.2.3
beatResources
- custom resources for celery beat.requests.cpu
param is mandatory for proper HPA work.2.4
cpuUtilizationBorder
- border percentage of average CPU utilization per pod for deployment.
Limiting network access to Mastermind APIs
Waldur Helm allows limiting network access to Mastermind API endpoints - i.e. /api/
, /api-auth/
, /admin/
- based on whitelisting the subnets from where access is allowed. To define a list of allowed subnets in CIDR format for the all the API endpoint, please use ingress.whitelistSourceRange
option in values.yaml
. Example:
1 2 3 4 |
|
Given this value, only IPs from 192.168.22.0/24
subnet are able to access Waldur Mastermind APIs.
In case you want to limit access to /api/admin/
endpoint specifically, there is another option called ingress.whitelistSourceRangeAdmin
:
1 2 3 4 |
|
This will limit access to the admin endpoint only for 192.168.22.1
IP. Note: The whitelistSourceRangeAdmin
option takes precedence over whitelistSourceRange
.
In case of multiple subnets/IPs, comma separated list can be used as a value. E.g.: 192.168.22.1/32,192.168.21.0/24
. This works for both options.
Official documentation
Documentation of installation link: doc
Installing kubectl
- Download and install latest kubectl
1 |
|
- Add executable mode for kubectl
1 |
|
- Move kubectl binary into your PATH
1 |
|
- Check the version
1 |
|
- Show running Pods in cluster
1 2 3 4 5 6 7 8 9 10 11 |
|
Locust cofiguration
This chart uses Locust tool for stress testing.
Installation
Locust runs as another standalone Helm release.
Install Locust:
1 |
|
After release installation, some instructions regarding access to WEB UI for Locust printed in stdout.See this section for more information about UI interaction.
Configuration
You can change locust config with the folloving variables in locust-values.yaml
:
image.repository
- repository of locust imageimage.tag
- tag of locust imagemaster.config
- key-value configuration records for locust master (used as container env vars)master.config.locust-host
- URL of target mastermind service. See this doc for detailsmaster.config.target-host
- same asmaster.config.locust-host
master.config.locust-mode-master
- master mode flag. Please, don't change it, because for new versions of locust this flag is mandatory for a master node.master.config.locust-locustfile
- path to the injected locust file. Please, don't change file directory (/locust-tasks/
), because it is fixed mountpoint for pods. The filename itself can have any value, but should be the same as key in the configmap (worker.config.configmapName
).worker.config
- key-value configuration records for locust worker (used as container env vars).worker.config.configmapName
- name of configmap with locustfileworker.config.locust-mode-worker
- worker mode flag. Please, don't change it, because for new versions of locust this flag is mandatory for a worker node.worker.config.locust-locustfile
- path to the injected locust file. Same rules as formaster.config.locust-locustfile
.worker.config.locust-master-node-host
- hostname of the locust master service, which is formatted as<locust_release_name>-master-svc
worker.replicaCount
- number of locust workers
You can find available variables for master and worker configuration from chart desription and official locust documentation (most of the flags and args can be injected through env vars).
NB: The original helm chart image (greenbirdit/locust:0.9.0
)
has outdated locust version and doesn't support most of
the current env variables from the first link above.
Thus master.config.target-host
is used only for compatibility
and must be equal to master.config.locust-host
In the values.yaml
you need to setup the following vars (stressTesting
prefix):
enabled
- enable/disable stress testinglocustFilePath
- path to the locust file (should be in thewaldur/
directory)
Waldur Marketplace script plugin setup
Available options in values.yaml
:
waldur.marketplace.script.enabled
- enable/disable pluginwaldur.marketplace.script.dockerImages
- key-value structure, where key is a programming language and value - a corresponding docker image tagwaldur.marketplace.script.k8sNamespace
- Kubernetes namespace, where jobs will be executedwaldur.marketplace.script.kubeconfigPath
- path to local file with kubeconfig contentwaldur.marketplace.script.kubeconfig
- kubeconfig file content takes precedence over.kubeconfigPath
optionwaldur.marketplace.script.jobTimeout
- timeout for Kubernetes jobs
Mastermind templates configuration
If you want to configure custom mastermind templates, you should:
-
Setup
waldur.mastermindTemplating.mastermindTemplatesPath
in values.yaml (by default, it is equal tomastermind_templates/mastermind-templates.yaml
). Alternatively, you can usewaldur.mastermindTemplating.mastermindTemplates
containing.yaml
file strings to get rid of file usage. -
Put all the custom templates into the file in a following way:
NB: The keys in the file should have <waldur_application_name>/<event_name>_<postfix>.<extension>
, where <postfix>
can be either message
or subject
, and <extension>
- either txt
or html
1 2 3 4 5 |
|
Example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
|
Migration from Postgresql HA
Plan:
- Scale api, beat, worker -> 0
- Backup — using backup job
- group_vars/puhuri_core_prd - helm_pg_ha_enabled: no ===> CANCEL THE UPDATING PIPELINE!
- Run dependency update ==> leads to a working single psql
- Restore DB — using recovery job
- Run a common update pipeline
- Validate that login works
- Drop old psql ha, drop pvc
1 2 3 4 5 6 7 8 9 10 11 12 |
|
Official documentation
Documentation of installation link: doc
Installing minikub
-
Download and install minikube
-
For Debial/Ubuntu:
1 2 |
|
- For Fedora/Red Hat
1 2 |
|
- Others (direct installation)
1 2 |
|
- Set docker as a default driver
1 2 3 |
|
- Start local kubernetes cluster
1 2 3 4 5 6 7 |
|
Min.io configuration
Min.io storage is used as a database backup storage.
Add bitnami
repo to helm:
1 |
|
Install minio
release:
1 |
|
You can change minio
config with next vars (in minio.values
file):
accessKey.password
- access key id for storagesecretKey.password
- secret key itselfserviceAccount.name
- name of the service account for MinIOpersistence.enabled
- persistence enabling flagpersistence.size
- size of storage per each podingress
- ingress settingsdefaultBuckets
- default buckets created after release installation (comma-separated list of strings)
For more configuration values follow this link.
In Waldur Helm values.yaml
you need to setup:
minio.accessKey
- should be same asaccessKey
inminio.values.yaml
minio.secretKey
- should be same assecretKey
inminio.values.yaml
minio.bucketName
- should be same as a value fromdefaultBuckets
list inminio-values.yaml
minio.endpoint
- access URL tominio
storage (minio
service host and port). See this doc for details.
PostgreSQL backup configuration
There are the following jobs for backups management:
-
CronJob for backups creation (running by a schedule
postgresBackup.schedule
) -
CronJob for backups rotation (running by a schedule
postgresBackup.rotationSchedule
)
Backup configuration values (postgresBackup
prefix):
-
enabled
- boolean flag for enabling/disabling backups -
schedule
- cron-like schedule for backups -
rotationSchedule
- cron-like schedule for backups rotation -
maxNumber
- maximum number of backups to store -
image
- Docker image containingpotgres
andminio
(client) binaries (opennode/postgres-minio by default)
Backups restoration
To restore backups you need to connect to the restoration pod. The major prerequisite for this is stopping the Waldur backend pods to avoid errors. NB: During restoration process, the site will be unavailable. For this, please execute the following lines in the Kubernetes node:
1 2 3 4 5 6 |
|
This will give you access to a terminal of a restoration pod. In this shell, please, execute the command:
1 |
|
This will print the recent 5 backups available for restoration. Example:
1 2 3 4 5 6 7 8 9 10 11 |
|
As you can see, the backup name contains the date and time when it was created in YYYY-mm-dd-HH-MM
format. You can freely choose the one you need.
1 2 3 4 5 6 7 8 9 10 |
|
Restoration from external backup
If you want to use a pre-created backup from an external system, copy the backup file:
- Copy the backup file to your local machine
-
Copy the file to pod
1 2
export RESTORATION_POD_NAME=$(kubectl get pods --template '{{range .items}}{{.metadata.name}}{{"\n"}}{{end}}' | grep restore) kubectl cp <BACKUP_FILE> $RESTORATION_POD_NAME:/tmp/backup.sql.gz
-
Connect to pod's terminal
1
kubectl exec -it $RESTORATION_POD_NAME -- bash
-
Apply the backup
1 2 3 4 5 6 7
gzip -d /tmp/backup.sql.gz # Be careful: the next lines have potentially danger operations psql -d postgres -c "SELECT pg_terminate_backend(pg_stat_activity.pid) FROM pg_stat_activity WHERE pg_stat_activity.datname = 'waldur' AND pid <> pg_backend_pid();" psql -d postgres -c 'DROP DATABASE waldur;' createdb waldur psql -f /tmp/backup.sql rm /tmp/backup.sql
PostgreSQL HA chart configuration
bitnami/postgresql-ha is used as a highly available database for Waldur.
Standalone installation
Add bitnami
repo to helm:
1 |
|
Install postgresql-ha
release:
1 2 |
|
NB: the value postgresql.HAEnabled
for waldur release must be true
.
Chart configuration
You can change default PostgreSQL config with
the following variables in values.yaml
(postgresql-ha-values.yaml
file):
postgresql.database
- name of a database. NB: must matchpostgresql.database
value inwaldur/values.yaml
postgresql.username
- name of a database user. NB: must matchpostgresql.username
value inwaldur/values.yaml
postgresql.password
- password of a database userpostgresql.replicaCount
- number of db replicaspostgresql.syncReplication
- enable/disable synchronous replicationpostgresql.repmgrUsername
- username ofrepmgr
userpostgresql.repmgrPassword
- password ofrepmgr
userpersistence.size
- size of a database (for each replica)pgpoolImage.tag
- tag ofPgpool
image. Possible tags for default image can be found herepostgresqlImage.tag
- tag ofPostgreSQL
image. Possible tags for default image can be found herepgpoolImage.tag
- registry ofPgpool
image.postgresqlImage.tag
- registry ofPostgreSQL
image.
More information related to possible values here.
Dependency installation
Waldur Helm chart supports PostgreSQL HA installation as a dependency.
For this, set postgresqlha.enabled
to true
and update related settings in postgresqlha
section in waldur/values.yaml
NB: the value postgresql.enabled
and externalDB.enabled
must be false
.
Prior Waldur installation, update chart dependencies:
1 |
|
PostgreSQL chart configuration (without HA support)
bitnami/postgresql chart is used as a database for Waldur.
Standalone installation
Add bitnami
repo to helm:
1 |
|
Install postgresql
release:
1 |
|
NB: the values postgresql.enabled
and postgresqlha.enabled
must be false
.
Chart configuration
You can change default PostgreSQL config with the following variables in postgresql-values.yaml
:
auth.database
- name of a database. NB: must matchpostgresql.database
value inwaldur/values.yaml
auth.username
- name of a database user. NB: must matchpostgresql.username
value inwaldur/values.yaml
auth.password
- password of a database userprimary.persistence.size
- size of a databaseimage.tag
- tag ofPostgreSQL
image. Possible tags for default image can be found hereimage.registry
- registry ofPostgreSQL
image.
More information related to possible values here.
Dependency installation
Waldur Helm chart supports PostgreSQL installation as a dependency.
For this, set postgresql.enabled
to true
and update related settings in postgresql
section in waldur/values.yaml
NB: the value postgresqlha.enabled
and externalDB.enabled
must be false
.
Prior Waldur installation, update chart dependencies:
1 |
|
Proxy setup for Waldur components
You can setup the proxy environment variables https_proxy
, http_proxy
and no_proxy
for Waldur component containers.
For this, please set values for the proxy.httpsProxy
, proxy.httpProxy
and proxy.noProxy
variables in waldur/values.yaml
file.
Example:
1 2 3 4 |
|
Note: you can set variables separately, i.e. leave some of them blank:
1 2 3 4 |
|
In the previous example, the https_proxy
env variable won't be present in the containers.
RabbitMQ configuration
For rabbitmq installation, bitnami/rabbitmq is used.
Installation
Add bitnami
repo to helm:
1 |
|
Install rabbitmq-ha release:
1 |
|
Configuration
You can change rabbitmq config with the following variables in rmq-values.yaml
:
replicaCount
- number RMQ instancespersistence.enabled
- enable/disable persistencepersistence.size
- size for singe PVpersistence.storageClass
- storage class for PVauth.username
- username for RMQ userauth.password
- password for RMQ user
For more config values, see this section
In values.yaml
file, you need to setup the following vars (rabbitmq
prefix):
user
- should be same asauth.username
in thermq-values.yaml
filepassword
- should be same asauth.password
in thermq-values.yaml
filehost
- rabbitmq-ha service hostname (See this doc for details)customManagementPort
- custom port for rabbitmq management interfacecustomAMQPPort
- custom port for AMQP access
SAML2 configuration
To configure SAML2 for Waldur:
- Enable SAML2 support in
values.yaml
: addSAML2
string intowaldur.authMethods
list - Set source directory in
waldur.saml2.dir
- Place necessary files in the directory
with the following manner (
.
is the source directory root):sp.crt
->./
sp.pem
->./
saml2.conf.py
->./
Service endpoints
For communication inside a cluster, pods use services. Usually, that needs to define internal endpoints with service URL format.
NB: It is important to set up namespace
part correctly.
If not, requests can come to unexpected service, which will cause errors.
Endpoint format
Fully qualified endpoint format is:
1 |
|
Where
<service-name>.<namespace>.svc.<cluster>
- hostname of service<service-port>
- port of service
For example:
- hostname is
elasticsearch-master.elastic.svc.cluster.local
- service port is
9200
- final URL is
http://elasticsearch-master.elastic.svc.cluster.local:9200
If pods run in the same namespace and cluster, it can be simplified to:
1 |
|
For example: http://elasticsearch-master:9200
TLS configuration instructions
To enable tls globally please set ingress.tls.enabled=true
in values.yaml
Let’s Encrypt setup
It you want co configure letsencrypt certification, you need to:
- Set
ingress.tls.source="letsEncrypt"
invalues.yaml
- Create namespace for cert-manager
1 |
|
- Add repository and update repos list
1 2 |
|
- Install cert-manager release
1 2 3 4 5 |
|
- After that,
waldur
release is ready for installation.
Your own certificate
In case, when you want to use own certificate, you need to:
- Set
ingress.tls.source="secret"
invalues.yaml
- Set
ingress.tls.secretsDir
variable to directory with yourtls.crt
andtls.key
files. By default it is set totls
- After that,
waldur
release is ready for installation
White-labeling instructions
To setup white-labeling, you can define next variables in waldur/values.yaml
file:
shortPageTitle
- custom prefix for page titlemodePageTitle
- custom page titleloginLogoPath
- path to custom.png
image file for login page (should be inwaldur/
chart directory)sidebarLogoPath
- path to custom.png
image file for sidebar header (should be inwaldur/
chart directory)sidebarLogoDarkPath
- path to custom.png
image file for sidebar header in dark mode (should be inwaldur/
chart directory)poweredByLogoPath
- path to custom.png
image file for "powered by" part of login page (should be inwaldur/
chart directory)faviconPath
- path to custom favicon.png
image filetosHtmlPath
- path to custom terms of service file (tos.html
)privacyHtmlPath
- path to custom privacy statement file (privacy.html
)brandColor
- Hex color definition is used in HomePort landing page for login button.brandLabelColor
- Hex color definition is used in HomePort landing page for font color of login button.heroImagePath
- Relative path to image rendered at hero section of HomePort landing page.heroLinkLabel
- Label for link in hero section of HomePort landing page. It can be lead to support site or blog post.heroLinkUrl
- Link URL in hero section of HomePort landing page.siteDescription
- text at hero section of HomePort landing page.
NB:
- the
*Path
values take place only if respectful*Url
values are not specified. If both types are defined, the precedence is taken byURL
(*Url
) for all cases. - all of imported files must be within chart root directory
Alternatively, TOS and PP files content can be provided as multiline values in tosHtml
and privacyHtml
options respectfully.
If defined, they take precedence over the aforementioned ones.
Ended: Docs
Ended: Helm
Ended: Deployment
Identities ↵
LDAP
Waldur allows you to authenticate using identities from a LDAP server.
Prerequisites
- Below it is assumed that LDAP server is provided by FreeIPA. Although LDAP authentication would work with any other LDAP server as well, you may need to customize configuration for Waldur MasterMind.
- Please ensure that Waldur Mastermind API server has access to the LDAP server. By default LDAP server listens on TCP and UDP port 389, or on port 636 for LDAPS (LDAP over SSL). If this port is filtered out by firewall, you wouldn't be able to authenticate via LDAP.
- You should know LDAP server URI, for example, FreeIPA demo server has
ldap://ipa.demo1.freeipa.org
. - You should know username and password of LDAP admin user. For example, FreeIPA demo server uses username=admin and password=Secret123.
Add LDAP configuration to Waldur Mastermind configuration
Example configuration is below, please adjust to your specific deployment.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 |
|
Configuration above is based on LDAP server exposed by FreeIPA. To make it work, there are some things that need to be verified in FreeIPA:
- Ensure that admins and support groups exist in LDAP server. You may do it using FreeIPA admin UI.
- If user is assigned to admins group in LDAP, he becomes staff in Waldur. If user is assigned to support group in LDAP, he becomes support user in Waldur. For example, consider the manager user which belong to both groups:
Field mapping
displayName
attribute in LDAP is mapped to full_name attribute in Waldur.
mail
field in LDAP is mapped to email attribute in Waldur.
Consider for example, the following user attributes in LDAP:
Here's how it is mapped in Waldur:
And here's how it is displayed when user initially logs into Waldur via HomePort:
MyAccessID
Waldur supports integration with MyAccessID identity service.
The MyAccessID Identity and Access Management Service is provided by GEANT with the purpose of offering a common Identity Layer for Infrastructure Service Domains (ISDs).
The AAI proxy of MyAccessID connects Identity Providers from eduGAIN, specific IdPs which are delivered in context of ISDs such as HPC IdPs, eIDAS eIDs and potentially other IdPs as requested by ISDs.
MyAccessID delivers the Discovery Service used during the user authentication process for users to choose their IdP. It enables the user to register an account in the Account Registry, to link different identities and it guarantees the uniqueness and persistence of the user identifier towards connected ISDs.
To enable MyAccessID, please register a new client for Waldur deployment and set configuration settings for MyAccessID. Check configuration guide for available settings.
Fetch user data using CUID of a user
You can use CUID of user in order to fetch user permissions from MyAccessID registry. This document describes how to perform it via Waldur shell.
TARA
Waldur supports integration with TARA authentication service.
To enable it, please register a new client for Waldur deployment and set configuration settings for TARA. Check configuration guide for available settings.
eduGAIN
Overview
eduGAIN is a global federation of identity and service providers, based technically on SAML2.
In order to allow eduGAIN users to access Waldur, there are two steps:
- Waldur deployment must be registered as a service provider in eduGAIN federation.
- Waldur must get a list of identities that are trusted for authentication.
Tip
SAML is a complicated and fragile technology. GEANT provides an alternative to direct integration of SAML - eduTEAMS, which exposes an OpenID Connect protocol for service providers.
Waldur relies on djangosaml2 for the heavylifting of SAML processing, so for fine tuning configuration, contact corresponding project documentation.
Registering Waldur as Service Provider
Add SAML configuration to Waldur Mastermind configuration
Example configuration is below, please adjust to your specific deployment. Once applied, service metadata will be
visible at Waldur deployment URL: https://waldur.example.com/api-auth/saml2/metadata/
. That data needs to be
propagated to the federation operator for inclusion into the federation.
Tip
Managed ansible simplifies configuration of the eduGAIN integration and should be a preferred method for all supported deployments.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 |
|
Example of generated metadata
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 |
|
Adding trusted identity providers
In order to configure Waldur to use SAML2 authentication you should specify identity provider metadata.
- If metadata XML is stored locally, it is cached in the local SQL database. Usually metadata XML file is big, so it
is necessary to use local cache in this case. But you should ensure that metadata XML file is refreshed via cron
on a regular basis. A management command
waldur sync_saml2_providers
performs refreshing of the data. - If metadata XML is accessed remotely, it is not cached in SQL database. Therefore you should ensure that metadata
XML is small enough. In this case you should download metadata signing certificate locally and specify its path in
Waldur configuration. The certificate is used to retrieve the metadata securely. Please note that security
certificates are updated regularly, therefore you should update configuration whenever certificate is updated.
By convention, both metadata signing certificate and metadata itself are downloaded to
/etc/waldur/saml2
in Waldur Mastermind instances.
References
TAAT configuration
TaaT certificates can be downloaded from: http://taat.edu.ee/main/dokumendid/sertifikaadid/.
Metadata URL for test hub is https://reos.taat.edu.ee/saml2/idp/metadata.php and for production hub is https://sarvik.taat.edu.ee/saml2/idp/metadata.php. Note, the certificate must correspond to the hub you want connect to.
Using Janus
Janus is a self-service for managing Service Provider records.
- Create a new connection:
New connection ID must be equal to the base_url in saml.conf.py + /apu-auth/saml2/metadata/
- Choose SAML 2.0 SP for connection type.
- Click Create button
- In connection tab select or create ARP. Fields that ARP include must be in the saml_attribute_mapping.
- Navigate to the Import metadata tab and paste same URL as in the first step. Click on the Get metadata.
- Navigate to the Validate tab and check whether all the tests pass. You can fix metadata in Metadata tab.
HAKA configuration
Production hub metadata is described at https://wiki.eduuni.fi/display/CSCHAKA/Haka+metadata.
Test hub metadata is described at https://wiki.eduuni.fi/display/CSCHAKA/Verifying+Haka+compatibility.
FEDI configuration
Production hub metadata is described at https://fedi.litnet.lt/en/metadata.
Discovery is supported: https://discovery.litnet.lt/simplesaml/module.php/discopower/disco.php.
eduTEAMS
Waldur supports integration with eduTEAMS identity service.
To enable it, please register a new client for Waldur deployment and set configuration settings for eduTEAMS. Check configuration guide for available settings.
Fetch user data using CUID of a user
You can use CUID of user in order to fetch user permissions. This file describes how to perform it, you only need to provide CUID as a username.
FreeIPA
Tip
For integrating FreeIPA as source of identities, please see LDAP. This module is about synchronising users from Waldur to FreeIPA
For situations when you would like to provide access to services based on the Linux usernames, e.g. for SLURM deployments, you might want to map users from Waldur (e.g. created through eduGAIN) to an external FreeIPA service.
To do that, you need to enable module and define settings for accessing FreeIPA REST APIs. See Waldur configuration guide for the list of supported FreeIPA settings.
At the moment at most one deployment of FreeIPA per Waldur is supported.
Keycloak
Waldur supports integration with Keycloak identity manager.
Below is a guide to configure Keycloak OpenID Connect client and Waldur intergration.
Configuring Keycloak
Instructions below are aimed to provide a basic configuration of Keycloak, please refer to Keycloak documentation for full details.
- Login to admin interface of Keycloak.
- Create a new realm (or use existing)
- Open a menu with a list of clients.
- Add a new client for Waldur.
- Change client's access type to "confidential".
- Change client's Valid redirect URIs to "*".
- You can get secret code for the client configuration
- You can find the settings required for configuration of Waldur under the following path on your Keycloak deployment (change
test-waldur
to the realm that you are using):/auth/realms/test-waldur/.well-known/openid-configuration
Configuring Waldur
-
Add Keycloak related configuration to Mastermind's
override.py
:1 2 3 4 5 6
WALDUR_AUTH_SOCIAL.update({'KEYCLOAK_AUTH_URL': 'https://KEYCLOAK_ADDRESS:8080/auth/realms/test-waldur/.well-known/openid-configuration', 'KEYCLOAK_CLIENT_ID': 'CLIENT_ID', 'KEYCLOAK_SECRET': 'SECRET', 'KEYCLOAK_TOKEN_URL': 'https://KEYCLOAK_ADDRESS:8080/auth/realms/test-waldur/protocol/openid-connect/token', 'KEYCLOAK_USERINFO_URL': 'https://KEYCLOAK_ADDRESS:8080/auth/realms/test-waldur/protocol/openid-connect/userinfo' })
-
Make sure
SOCIAL_SIGNUP
is added to the list of available authentication methods:1
WALDUR_CORE['AUTHENTICATION_METHODS'] = ["LOCAL_SIGNIN", "SOCIAL_SIGNUP"]
Full Keycloak related configuration settings are available at Mastermind configuration file reference
Summary
Name | Protocol | Description |
---|---|---|
eduGAIN | SAML | Federation of research and educational providers supported by Geant |
eduTEAMS | OIDC | Group management service integrated with research and educational providers provided by Geant |
FreeIPA | REST API | Support for synchronisation of Waldur identities with open-source Identity Management server |
Keycloak | OIDC | Open-source identity management server |
LDAP | LDAP/S | Support of identity servers over LDAP protocol |
TARA | OIDC | Estonian State Autentication service |
Ended: Identities
Mastermind configuration ↵
CLI guide
axes_list_attempts
List access attempts
axes_reset
Reset all access attempts and lockouts
axes_reset_failure_logs
Reset access failure log records older than given days.
1 2 3 4 |
|
axes_reset_ip
Reset all access attempts and lockouts for given IP addresses
1 2 3 4 |
|
axes_reset_ip_username
Reset all access attempts and lockouts for a given IP address and username
1 2 3 4 5 |
|
axes_reset_logs
Reset access log records older than given days.
1 2 3 4 |
|
axes_reset_username
Reset all access attempts and lockouts for given usernames
1 2 3 4 |
|
clean_settings_cache
Clean API configuration settings cache.
cleanup_stale_event_types
Cleanup stale event types in all hooks.
copy_category
Copy structure of categories for the Marketplace
1 2 3 4 5 |
|
create_provider
Create a service provider with a linked customer and load categories
1 2 3 4 5 |
|
createstaffuser
Create a user with a specified username and password. User will be created as staff.
1 2 3 4 5 6 |
|
drop_leftover_openstack_projects
Drop leftover projects from remote OpenStack deployment. Leftovers are resources marked as terminated in Waldur but still present in the remote OpenStack. Such inconsistency may be caused by split brain problem in the distributed database.
1 2 3 4 5 6 7 8 9 |
|
dumpusers
Dumps information about users, their organizations and projects.
1 2 3 4 5 6 |
|
export_ami_catalog
Export catalog of Amazon images.
export_auth_social
Export OIDC auth configuration as YAML format
1 2 3 4 5 6 |
|
export_offering
Export an offering from Waldur. Export data includes JSON file with an offering data and a thumbnail. Names of this files include offering ID.
1 2 3 4 5 6 7 |
|
import_ami_catalog
Import catalog of Amazon images.
1 2 3 4 5 6 7 |
|
import_auth_social
Import OIDC auth configuration in YAML format. The example of auth.yaml:
1 2 3 4 5 6 7 8 9 |
|
1 2 3 4 |
|
import_azure_image
Import Azure image
1 2 3 4 5 6 7 |
|
import_marketplace_orders
Create marketplace order for each resource if it does not yet exist.
import_offering
Import or update an offering in Waldur. You must define offering for updating or category and customer for creating.
1 2 3 4 5 6 7 8 9 10 11 |
|
import_reppu_usages
Import component usages from Reppu for a specified year and month.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
|
import_roles
Import roles configuration in YAML format
1 2 3 4 |
|
import_tenant_quotas
Import OpenStack tenant quotas to marketplace.
1 2 3 4 5 |
|
initsecuritygroups
Add default security groups with given names to all tenants.
1 2 3 4 |
|
load_categories
Loads a categories for the Marketplace
1 2 3 4 |
|
load_features
Import features in JSON format
1 2 3 4 5 6 7 8 |
|
load_notifications
Import notifications to DB
1 2 3 4 |
|
load_user_agreements
Imports privacy policy and terms of service into DB
1 2 3 4 5 6 7 8 |
|
move_project
Move Waldur project to a different organization.
1 2 3 4 5 6 7 |
|
move_resource
Move a marketplace resource to a different project.
1 2 3 4 5 6 7 |
|
override_constance_settings
Override settings stored in django-constance. The example of .yaml file:
1 2 3 4 5 6 7 |
|
1 2 3 4 5 6 |
|
override_roles
Override roles configuration in YAML format. The example of roles-override.yaml:
1 2 3 4 5 6 7 8 9 10 |
|
1 2 3 4 |
|
override_templates
Override templates
1 2 3 4 5 6 7 8 9 |
|
pgmigrate
Load data with disabled signals.
1 2 3 4 |
|
print_events_enums
Prints all event types as typescript enums.
print_features_description
Prints all Waldur feature description as typescript code.
print_features_docs
Prints all Waldur feature toggles in markdown format.
print_features_enums
Prints all Waldur feature toggles as typescript enums.
print_notifications
Prints Mastermind notifications with a description and templates
print_permissions_description
Prints all Waldur permissions description as typescript code.
print_settings_description
Prints all Waldur feature description as typescript code.
pull_openstack_volume_metadata
Pull OpenStack volumes metadata to marketplace.
1 2 3 4 5 |
|
pull_support_priorities
Pull priorities from support backend.
pull_support_users
Pull users from support backend.
push_tenant_quotas
Push OpenStack tenant quotas from marketplace to backend.
1 2 3 4 5 |
|
rebuild_billing
Create or update price estimates based on invoices.
removestalect
Remove Django event log records with stale content types.
set_constance_image
A custom command to set Constance image configs with CLI
1 2 3 4 5 |
|
status
Check status of Waldur MasterMind configured services
1 2 3 4 5 6 7 |
|
switching_backend_server
Backend data update if a server was switched.
sync_saml2_providers
Synchronize SAML2 identity providers.
sync_users
Sync users from Waldur to Rancher.
Configuration options
Static options
WALDUR_AUTH_SAML2 plugin
Default value:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 |
|
ALLOW_TO_SELECT_IDENTITY_PROVIDER
Type: bool
ATTRIBUTE_MAP_DIR
Type: str
Directory with attribute mapping
AUTHN_REQUESTS_SIGNED
Type: str
Indicates if the authentication requests sent should be signed by default
CATEGORIES
Type: list
Links to the entity categories
CERT_FILE
Type: str
PEM formatted certificate chain file
DEBUG
Type: bool
Set to True to output debugging information
DEFAULT_BINDING
Type: str
DESCRIPTION
Type: str
Service provider description (required by CoC)
DIGEST_ALGORITHM
Type: Optional[str]
Identifies the Message Digest algorithm URL according to the XML Signature specification (SHA1 is used by default)
DISCOVERY_SERVICE_LABEL
Type: Optional[str]
DISCOVERY_SERVICE_URL
Type: Optional[str]
DISPLAY_NAME
Type: str
Service provider display name (required by CoC)
ENABLE_SINGLE_LOGOUT
Type: bool
IDENTITY_PROVIDER_LABEL
Type: Optional[str]
IDENTITY_PROVIDER_URL
Type: Optional[str]
IDP_METADATA_LOCAL
Type: list
IdPs metadata XML files stored locally
IDP_METADATA_REMOTE
Type: list
IdPs metadata XML files stored remotely
KEY_FILE
Type: str
PEM formatted certificate key file
LOGOUT_REQUESTS_SIGNED
Type: str
Indicates if the entity will sign the logout requests
LOG_FILE
Type: str
Empty to disable logging SAML2-related stuff to file
LOG_LEVEL
Type: str
Log level for SAML2
MANAGEMENT_URL
Type: str
The endpoint for user details management.
NAME
Type: str
Name used for assigning the registration method to the user
NAMEID_FORMAT
Type: Optional[str]
Identified NameID format to use. None means default, empty string ("") disables addition of entity
OPTIONAL_ATTRIBUTES
Type: list
SAML attributes that may be useful to have but not required
ORGANIZATION
Type: dict
Organization responsible for the service (you can set multilanguage information here)
PRIVACY_STATEMENT_URL
Type: str
URL with privacy statement (required by CoC)
REGISTRATION_AUTHORITY
Type: str
Registration authority required by mdpi
REGISTRATION_INSTANT
Type: str
Registration instant time required by mdpi
REGISTRATION_POLICY
Type: str
Registration policy required by mdpi
REQUIRED_ATTRIBUTES
Type: list
SAML attributes that are required to identify a user
SAML_ATTRIBUTE_MAPPING
Type: dict
Mapping between SAML attributes and User fields
SIGNATURE_ALGORITHM
Type: Optional[str]
Identifies the Signature algorithm URL according to the XML Signature specification (SHA1 is used by default)
XMLSEC_BINARY
Type: str
Full path to the xmlsec1 binary program
WALDUR_AUTH_SOCIAL plugin
Default value:
1 2 3 4 5 6 7 8 9 10 |
|
ENABLE_EDUTEAMS_SYNC
Type: bool
Enable eduTEAMS synchronization with remote Waldur.
REMOTE_EDUTEAMS_CLIENT_ID
Type: str
ID of application used for OAuth authentication.
REMOTE_EDUTEAMS_ENABLED
Type: bool
Enable remote eduTEAMS extension.
REMOTE_EDUTEAMS_REFRESH_TOKEN
Type: str
Token is used to authenticate against user info endpoint.
REMOTE_EDUTEAMS_SECRET
Type: str
Application secret key.
REMOTE_EDUTEAMS_SSH_API_PASSWORD
Type: str
Password for SSH API URL
REMOTE_EDUTEAMS_SSH_API_URL
Type: str
API URL SSH keys
REMOTE_EDUTEAMS_SSH_API_USERNAME
Type: str
Username for SSH API URL
REMOTE_EDUTEAMS_TOKEN_URL
Type: str
The token endpoint is used to obtain tokens.
REMOTE_EDUTEAMS_USERINFO_URL
Type: str
It allows to get user data based on userid aka CUID.
WALDUR_CORE plugin
Default value:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 |
|
ATTACHMENT_LINK_MAX_AGE
Type: timedelta
Max age of secure token for media download.
AUTHENTICATION_METHODS
Type: List[str]
List of enabled authentication methods.
BACKEND_FIELDS_EDITABLE
Type: bool
Allows to control /admin writable fields. If this flag is disabled it is impossible to edit any field that corresponds to backend value via /admin. Such restriction allows to save information from corruption.
COUNTRIES
Type: List[str]
It is used in organization creation dialog in order to limit country choices to predefined set.
CREATE_DEFAULT_PROJECT_ON_ORGANIZATION_CREATION
Type: bool
Enables generation of the first project on organization creation.
DEFAULT_IDP
Type: str
Triggers authentication flow at once.
EMAIL_CHANGE_MAX_AGE
Type: timedelta
Max age of change email request.
ENABLE_ACCOUNTING_START_DATE
Type: bool
Allows to enable accounting for organizations using value of accounting_start_date field.
ENABLE_GEOIP
Type: bool
Enable detection of coordinates of virtual machines.
ENABLE_STRICT_CHECK_ACCEPTING_INVITATION
Type: bool
If this is true and user email is pre-validated then accepting invitation to only do that if user’s email and email of the invitation fully match.
EXTENSIONS_AUTOREGISTER
Type: bool
Defines whether extensions should be automatically registered.
EXTERNAL_LINKS
Type: List[ExternalLink]
Render external links in dropdown in header. Each item should be object with label and url fields. For example: {"label": "Helpdesk", "url": "https://example.com/
"}
GROUP_INVITATION_LIFETIME
Type: timedelta
Defines for how long group invitation remains valid.
HOMEPORT_SENTRY_DSN
Type: Optional[str]
Sentry Data Source Name for Waldur HomePort project.
HOMEPORT_SENTRY_ENVIRONMENT
Type: str
Sentry environment name for Waldur Homeport.
HOMEPORT_SENTRY_TRACES_SAMPLE_RATE
Type: float
Percentage of transactions sent to Sentry for tracing.
HOMEPORT_URL
Type: str
It is used for rendering callback URL in HomePort.
HTTP_CHUNK_SIZE
Type: int
Chunk size for resource fetching from backend API. It is needed in order to avoid too long HTTP request error.
INVITATIONS_ENABLED
Type: bool
Allows to disable invitations feature.
INVITATION_CIVIL_NUMBER_LABEL
Type: str
Custom label for civil number field in invitation creation dialog.
INVITATION_CREATE_MISSING_USER
Type: bool
Allow to create FreeIPA user using details specified in invitation if user does not exist yet.
INVITATION_DISABLE_MULTIPLE_ROLES
Type: bool
Do not allow user to grant multiple roles in the same project or organization using invitation.
INVITATION_LIFETIME
Type: timedelta
Defines for how long invitation remains valid.
INVITATION_MAX_AGE
Type: Optional[timedelta]
Max age of invitation token. It is used in approve and reject actions.
INVITATION_TAX_NUMBER_LABEL
Type: str
Custom label for tax number field in invitation creation dialog.
INVITATION_USE_WEBHOOKS
Type: bool
Allow sending of webhooks instead of sending of emails.
INVITATION_WEBHOOK_TOKEN_CLIENT_ID
Type: str
Client ID to get access token from Keycloak.
INVITATION_WEBHOOK_TOKEN_SECRET
Type: str
Client secret to get access token from Keycloak.
INVITATION_WEBHOOK_TOKEN_URL
Type: str
Keycloak URL to get access token.
INVITATION_WEBHOOK_URL
Type: str
Webhook URL for sending invitations.
LOCAL_IDP_LABEL
Type: str
The label of local auth.
LOCAL_IDP_MANAGEMENT_URL
Type: str
The URL for management of local user details.
LOCAL_IDP_NAME
Type: str
The name of local auth.
LOCAL_IDP_PROTECTED_FIELDS
Type: List[str]
The list of protected fields for local IdP.
LOGGING_REPORT_DIRECTORY
Type: str
Directory where log files are located.
LOGGING_REPORT_INTERVAL
Type: timedelta
Files older that specified interval are filtered out.
MASTERMIND_URL
Type: str
It is used for rendering callback URL in MasterMind.
MATOMO_SITE_ID
Type: Optional[int]
Site ID is used by Matomo analytics application.
MATOMO_URL_BASE
Type: Optional[str]
URL base is used by Matomo analytics application.
NATIVE_NAME_ENABLED
Type: bool
Allows to render native name field in customer and user forms.
NOTIFICATIONS_PROFILE_CHANGES
Type: dict
Configure notifications about profile changes of organization owners.
NOTIFICATION_SUBJECT
Type: str
It is used as a subject of email emitted by event logging hook.
OECD_FOS_2007_CODE_MANDATORY
Type: bool
Field oecd_fos_2007_code must be required for project.
ONLY_STAFF_CAN_INVITE_USERS
Type: bool
Allow to limit invitation management to staff only.
PROTECT_USER_DETAILS_FOR_REGISTRATION_METHODS
Type: List[str]
List of authentication methods for which a manual update of user details is not allowed.
REQUEST_HEADER_IMPERSONATED_USER_UUID
Type: str
The request header, which contains the user UUID of the user to be impersonated.
RESPONSE_HEADER_IMPERSONATOR_UUID
Type: str
The response header, which contains the UUID of the user who requested the impersonation.
SELLER_COUNTRY_CODE
Type: Optional[str]
Specifies seller legal or effective country of registration or residence as an ISO 3166-1 alpha-2 country code. It is used for computing VAT charge rate.
SHOW_ALL_USERS
Type: bool
Indicates whether user can see all other users in api/users/
endpoint.
SUPPORT_PORTAL_URL
Type: str
Support portal URL is rendered as a shortcut on dashboard
TOKEN_KEY
Type: str
Header for token authentication.
TOKEN_LIFETIME
Type: timedelta
Defines for how long user token should remain valid if there was no action from user.
TRANSLATION_DOMAIN
Type: str
Identifier of translation domain applied to current deployment.
USER_MANDATORY_FIELDS
Type: List[str]
List of user profile attributes that would be required for filling in HomePort. Note that backend will not be affected. If a mandatory field is missing in profile, a profile edit view will be forced upon user on any HomePort logged in action. Possible values are: description, email, full_name, job_title, organization, phone_number
USER_REGISTRATION_HIDDEN_FIELDS
Type: List[str]
List of user profile attributes that would be concealed on registration form in HomePort. Possible values are: job_title, registration_method, phone_number
USE_ATOMIC_TRANSACTION
Type: bool
Wrap action views in atomic transaction.
VALIDATE_INVITATION_EMAIL
Type: bool
Ensure that invitation and user emails match.
WALDUR_FREEIPA plugin
Default value:
1 2 3 4 5 6 7 8 9 |
|
BLACKLISTED_USERNAMES
Type: list
List of username that users are not allowed to select
ENABLED
Type: bool
Enable integration of identity provisioning in configured FreeIPA
GROUPNAME_PREFIX
Type: str
Prefix to be appended to all group names created in FreeIPA by Waldur
GROUP_SYNCHRONIZATION_ENABLED
Type: bool
Optionally disable creation of user groups in FreeIPA matching Waldur structure
HOSTNAME
Type: str
Hostname of FreeIPA server
PASSWORD
Type: str
Password of FreeIPA user with administrative privileges
USERNAME
Type: str
Username of FreeIPA user with administrative privileges
USERNAME_PREFIX
Type: str
Prefix to be appended to all usernames created in FreeIPA by Waldur
VERIFY_SSL
Type: bool
Validate TLS certificate of FreeIPA web interface / REST API
WALDUR_HPC plugin
Default value:
1 2 3 4 5 6 7 8 9 10 11 |
|
ENABLED
Type: bool
Enable HPC-specific hooks in Waldur deployment
EXTERNAL_AFFILIATIONS
Type: List[str]
List of user affiliations (eduPersonScopedAffiliation fields) that define if the user belongs to external organization.
EXTERNAL_CUSTOMER_UUID
Type: str
UUID of a Waldur organization (aka customer) where new external users would be added
EXTERNAL_EMAIL_PATTERNS
Type: List[str]
List of user email patterns (as regex) that define if the user belongs to external organization.
EXTERNAL_LIMITS
Type: dict
Overrided default values for SLURM offering to be created for users belonging to external organization.
INTERNAL_AFFILIATIONS
Type: List[str]
List of user affiliations (eduPersonScopedAffiliation fields) that define if the user belongs to internal organization.
INTERNAL_CUSTOMER_UUID
Type: str
UUID of a Waldur organization (aka customer) where new internal users would be added
INTERNAL_EMAIL_PATTERNS
Type: List[str]
List of user email patterns (as regex) that define if the user belongs to internal organization.
INTERNAL_LIMITS
Type: dict
Overrided default values for SLURM offering to be created for users belonging to internal organization.
OFFERING_UUID
Type: str
UUID of a Waldur SLURM offering, which will be used for creating allocations for users
PLAN_UUID
Type: str
UUID of a Waldur SLURM offering plan, which will be used for creating allocations for users
WALDUR_MARKETPLACE plugin
Default value:
1 2 3 4 5 6 7 8 9 10 |
|
ANONYMOUS_USER_CAN_VIEW_OFFERINGS
Type: bool
Allow anonymous users to see shared offerings in active, paused and archived states
ANONYMOUS_USER_CAN_VIEW_PLANS
Type: bool
Allow anonymous users to see plans
DISABLE_SENDING_NOTIFICATIONS_ABOUT_RESOURCE_UPDATE
Type: bool
Disable only resource update events.
ENABLE_RESOURCE_END_DATE
Type: bool
Allow to view and update resource end date.
ENABLE_STALE_RESOURCE_NOTIFICATIONS
Type: bool
Enable reminders to owners about resources of shared offerings that have not generated any cost for the last 3 months.
NOTIFY_ABOUT_RESOURCE_CHANGE
Type: bool
If true, notify users about resource changes from Marketplace perspective. Can generate duplicate events if plugins also log
NOTIFY_STAFF_ABOUT_APPROVALS
Type: bool
If true, users with staff role are notified when request for order approval is generated
TELEMETRY_URL
Type: str
URL for sending telemetry data.
TELEMETRY_VERSION
Type: int
Telemetry service version.
THUMBNAIL_SIZE
Type: tuple
Size of the thumbnail to generate when screenshot is uploaded for an offering.
WALDUR_MARKETPLACE_REMOTE_SLURM plugin
Default value:
1 |
|
USE_WALDUR_USERNAMES
Type: bool
Fetch usernames from Waldur rather then FreeIPA profiles.
WALDUR_MARKETPLACE_SCRIPT plugin
Default value:
1 2 3 4 5 6 7 8 9 10 11 |
|
DOCKER_CLIENT
Type: dict
Options for docker client. See also: https://docker-py.readthedocs.io/en/stable/client.html#docker.client.DockerClient
DOCKER_IMAGES
Type: dict
Key is command to execute script, value is a dictionary of image name and command.
DOCKER_REMOVE_CONTAINER
Type: bool
Remove Docker container after script execution
DOCKER_RUN_OPTIONS
Type: dict
Options for docker runtime. See also: https://docker-py.readthedocs.io/en/stable/containers.html#docker.models.containers.ContainerCollection.run
DOCKER_SCRIPT_DIR
Type: Optional[str]
Path to folder on executor machine where to create temporary submission scripts. If None uses OS-dependent location. OS X users, see https://github.com/docker/for-mac/issues/1532
K8S_CONFIG_PATH
Type: str
Path to Kubernetes configuration file
K8S_JOB_TIMEOUT
Type: int
Timeout for execution of one Kubernetes job in seconds
K8S_NAMESPACE
Type: str
Kubernetes namespace where jobs will be executed
SCRIPT_RUN_MODE
Type: str
Type of jobs deployment. Valid values: "docker" for simple docker deployment, "k8s" for Kubernetes-based one
WALDUR_OPENSTACK plugin
Default value:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 |
|
ALLOW_CUSTOMER_USERS_OPENSTACK_CONSOLE_ACCESS
Type: bool
If true, customer users would be offered actions for accessing OpenStack console
ALLOW_DIRECT_EXTERNAL_NETWORK_CONNECTION
Type: bool
If true, allow connecting of instances directly to external networks
DEFAULT_BLACKLISTED_USERNAMES
Type: list
Usernames that cannot be created by Waldur in OpenStack
DEFAULT_SECURITY_GROUPS
Type: tuple
Default security groups and rules created in each of the provisioned OpenStack tenants
MAX_CONCURRENT_PROVISION
Type: dict
Maximum parallel executions of provisioning operations for OpenStack resources
REQUIRE_AVAILABILITY_ZONE
Type: bool
If true, specification of availability zone during provisioning will become mandatory
SUBNET
Type: dict
Default allocation pool for auto-created internal network
TENANT_CREDENTIALS_VISIBLE
Type: bool
If true, generated credentials of a tenant are exposed to project users
WALDUR_PID plugin
Default value:
1 2 3 4 5 6 |
|
DATACITE
Type: dict
Settings for integration of Waldur with Datacite PID service. Collection DOI is used to aggregate generated DOIs.
WALDUR_SLURM plugin
Default value:
1 2 3 4 5 6 |
|
ALLOCATION_PREFIX
Type: str
Prefix for SLURM account name corresponding to Waldur allocation
CUSTOMER_PREFIX
Type: str
Prefix for SLURM account name corresponding to Waldur organization.
DEFAULT_LIMITS
Type: dict
Default limits of account that are set when SLURM account is provisioned.
ENABLED
Type: bool
Enable support for SLURM plugin in a deployment
PRIVATE_KEY_PATH
Type: str
Path to private key file used as SSH identity file for accessing SLURM master.
PROJECT_PREFIX
Type: str
Prefix for SLURM account name corresponding to Waldur project.
Other variables
DEFAULT_FROM_EMAIL
Type: str, default value: webmaster@localhost
Default email address to use for automated correspondence from Waldur.
DEFAULT_REPLY_TO_EMAIL
Type: str
Default email address to use for email replies.
EMAIL_HOOK_FROM_EMAIL
Type: str
Alternative email address to use for email hooks.
IMPORT_EXPORT_USE_TRANSACTIONS
Type: bool, default value: True
Controls if resource importing should use database transactions. Using transactions makes imports safer as a failure during import won’t import only part of the data set.
IPSTACK_ACCESS_KEY
Type: Optional[str]
Unique authentication key used to gain access to the ipstack API.
LANGUAGES
Type: List[tuple[str, str]], default value: (('en', 'English'), ('et', 'Eesti'))
The list is a list of two-tuples in the format (language code, language name) – for example, ('ja', 'Japanese').
LANGUAGE_CODE
Type: str, default value: en
Represents the name of a default language.
VERIFY_WEBHOOK_REQUESTS
Type: bool, default value: True
When webook is processed, requests verifies SSL certificates for HTTPS requests, just like a web browser.
Dynamic options
Branding
SITE_NAME
Type: str
Default value: Waldur
Human-friendly name of the Waldur deployment.
SHORT_PAGE_TITLE
Type: str
Default value: Waldur
It is used as prefix for page title.
FULL_PAGE_TITLE
Type: str
Default value: Waldur | Cloud Service Management
It is used as default page title if it's not specified explicitly.
SITE_DESCRIPTION
Type: str
Default value: Your single pane of control for managing projects, teams and resources in a self-service manner.
Description of the Waldur deployment.
Marketplace
SITE_ADDRESS
Type: str
It is used in marketplace order header.
SITE_EMAIL
Type: str
It is used in marketplace order header and UI footer.
SITE_PHONE
Type: str
It is used in marketplace order header and UI footer.
CURRENCY_NAME
Type: str
Default value: EUR
It is used in marketplace order details and invoices for currency formatting.
Notifications
COMMON_FOOTER_TEXT
Type: text_field
Common footer in txt format for all emails.
COMMON_FOOTER_HTML
Type: html_field
Common footer in html format for all emails.
Links
DOCS_URL
Type: url_field
Renders link to docs in header
HERO_LINK_LABEL
Type: str
Label for link in hero section of HomePort landing page. It can be lead to support site or blog post.
HERO_LINK_URL
Type: url_field
Link URL in hero section of HomePort landing page.
SUPPORT_PORTAL_URL
Type: url_field
Link URL to support portal. Rendered as a shortcut on dashboard
Theme
SIDEBAR_STYLE
Type: str
Default value: dark
Style of sidebar. Possible values: dark, light, accent.
BRAND_COLOR
Type: color_field
Default value: #3a8500
Hex color definition is used in HomePort landing page for login button.
BRAND_LABEL_COLOR
Type: color_field
Default value: #000000
Hex color definition is used in HomePort landing page for font color of login button.
DISABLE_DARK_THEME
Type: bool
Toggler for dark theme.
Images
SITE_LOGO
Type: image_field
The image used in marketplace order header.
SIDEBAR_LOGO
Type: image_field
The image rendered at the top of sidebar menu in HomePort.
SIDEBAR_LOGO_MOBILE
Type: image_field
The image rendered at the top of mobile sidebar menu in HomePort.
SIDEBAR_LOGO_DARK
Type: image_field
The image rendered at the top of sidebar menu in dark mode.
POWERED_BY_LOGO
Type: image_field
The image rendered at the bottom of login menu in HomePort.
HERO_IMAGE
Type: image_field
The image rendered at hero section of HomePort landing page.
LOGIN_LOGO
Type: image_field
A custom .png image file for login page
FAVICON
Type: image_field
A custom favicon .png image file
OFFERING_LOGO_PLACEHOLDER
Type: image_field
Default logo for offering
Service desk integration settings
WALDUR_SUPPORT_ENABLED
Type: bool
Default value: True
Toggler for support plugin.
WALDUR_SUPPORT_ACTIVE_BACKEND_TYPE
Type: str
Default value: atlassian
Type of support backend. Possible values: atlassian, zammad, smax.
WALDUR_SUPPORT_DISPLAY_REQUEST_TYPE
Type: bool
Default value: True
Toggler for request type displaying
Atlassian settings
ATLASSIAN_API_URL
Type: url_field
Default value: http://example.com/
Atlassian API server URL
ATLASSIAN_USERNAME
Type: str
Default value: USERNAME
Username for access user
ATLASSIAN_PASSWORD
Type: secret_field
Default value: PASSWORD
Password for access user
ATLASSIAN_EMAIL
Type: email_field
Email for access user
ATLASSIAN_TOKEN
Type: secret_field
Token for access user
ATLASSIAN_PROJECT_ID
Type: str
Service desk ID or key
ATLASSIAN_DEFAULT_OFFERING_ISSUE_TYPE
Type: str
Default value: Service Request
Issue type used for request-based item processing.
ATLASSIAN_EXCLUDED_ATTACHMENT_TYPES
Type: str
Comma-separated list of file extenstions not allowed for attachment.
ATLASSIAN_ISSUE_TYPES
Type: str
Default value: Informational, Service Request, Change Request, Incident
Comma-separated list of enabled issue types. First type is the default one.
ATLASSIAN_AFFECTED_RESOURCE_FIELD
Type: str
Affected resource field name
ATLASSIAN_DESCRIPTION_TEMPLATE
Type: str
Template for issue description
ATLASSIAN_SUMMARY_TEMPLATE
Type: str
Template for issue summary
ATLASSIAN_IMPACT_FIELD
Type: str
Default value: Impact
Impact field name
ATLASSIAN_ORGANISATION_FIELD
Type: str
Organisation field name
ATLASSIAN_RESOLUTION_SLA_FIELD
Type: str
Resolution SLA field name
ATLASSIAN_PROJECT_FIELD
Type: str
Project field name
ATLASSIAN_REPORTER_FIELD
Type: str
Default value: Original Reporter
Reporter field name
ATLASSIAN_CALLER_FIELD
Type: str
Default value: Caller
Caller field name
ATLASSIAN_SLA_FIELD
Type: str
Default value: Time to first response
SLA field name
ATLASSIAN_LINKED_ISSUE_TYPE
Type: str
Default value: Relates
Type of linked issue field name
ATLASSIAN_SATISFACTION_FIELD
Type: str
Default value: Customer satisfaction
Customer satisfaction field name
ATLASSIAN_REQUEST_FEEDBACK_FIELD
Type: str
Default value: Request feedback
Request feedback field name
ATLASSIAN_TEMPLATE_FIELD
Type: str
Template field name
ATLASSIAN_CUSTOM_ISSUE_FIELD_MAPPING_ENABLED
Type: bool
Default value: True
Should extra issue field mappings be applied
ATLASSIAN_SHARED_USERNAME
Type: bool
Is Service Desk username the same as in Waldur
ATLASSIAN_VERIFY_SSL
Type: bool
Toggler for SSL verification
ATLASSIAN_USE_OLD_API
Type: bool
Toggler for legacy API usage.
ATLASSIAN_USE_TEENAGE_API
Type: bool
Toggler for teenage API usage.
ATLASSIAN_USE_AUTOMATIC_REQUEST_MAPPING
Type: bool
Default value: True
Toggler for automatic request mapping.
ATLASSIAN_MAP_WALDUR_USERS_TO_SERVICEDESK_AGENTS
Type: bool
Toggler for mapping between waldur user and service desk agents.
ATLASSIAN_STRANGE_SETTING
Type: int
Default value: 1
A constant in the API path, sometimes differs
ATLASSIAN_PULL_PRIORITIES
Type: bool
Default value: True
Toggler for pulling priorities from backend
Zammad settings
ZAMMAD_API_URL
Type: url_field
Zammad API server URL. For example http://localhost:8080/
ZAMMAD_TOKEN
Type: secret_field
Authorization token.
ZAMMAD_GROUP
Type: str
The name of the group to which the ticket will be added. If not specified, the first group will be used.
ZAMMAD_ARTICLE_TYPE
Type: str
Default value: email
Type of a comment. Default is email because it allows support to reply to tickets directly in Zammadhttps://docs.zammad.org/en/latest/api/ticket/articles.html#articles/
ZAMMAD_COMMENT_MARKER
Type: str
Default value: Created by Waldur
Marker for comment. Used for separating comments made via Waldur from natively added comments.
ZAMMAD_COMMENT_PREFIX
Type: str
Default value: User: {name}
Comment prefix with user info.
ZAMMAD_COMMENT_COOLDOWN_DURATION
Type: int
Default value: 5
Time in minutes. Time in minutes while comment deletion is available https://github.com/zammad/zammad/issues/2687/, https://github.com/zammad/zammad/issues/3086/
SMAX settings
SMAX_API_URL
Type: url_field
SMAX API server URL. For example http://localhost:8080/
SMAX_TENANT_ID
Type: str
User tenant ID.
SMAX_LOGIN
Type: str
Authorization login.
SMAX_PASSWORD
Type: secret_field
Authorization password.
SMAX_ORGANISATION_FIELD
Type: str
Organisation field name.
SMAX_PROJECT_FIELD
Type: str
Project field name.
SMAX_AFFECTED_RESOURCE_FIELD
Type: str
Resource field name.
SMAX_REQUESTS_OFFERING
Type: str
Requests offering code for all issues.
SMAX_SECONDS_TO_WAIT
Type: int
Default value: 1
Duration in seconds of delay between pull user attempts.
SMAX_TIMES_TO_PULL
Type: int
Default value: 10
The maximum number of attempts to pull user from backend.
SMAX_CREATION_SOURCE_NAME
Type: str
Creation source name.
SMAX_VERIFY_SSL
Type: bool
Default value: True
Toggler for SSL verification
Proposal settings
PROPOSAL_REVIEW_DURATION
Type: int
Default value: 7
Review duration in days.
Table settings
USER_TABLE_COLUMNS
Type: str
Comma-separated list of columns for users table.
Localization
LANGUAGE_CHOICES
Type: str
Default value: en,et,lt,lv,ru,it,de,da,sv,es,fr,nb,ar,cs
List of enabled languages
User settings
AUTO_APPROVE_USER_TOS
Type: bool
Configure whether a user needs to approve TOS.
Features
customer.payments_for_staff_only
Make payments menu visible for staff users only.
customer.show_domain
Allows to hide domain field in organization detail.
invitations.civil_number_required
Make civil number field mandatory in invitation creation form.
invitations.conceal_civil_number
Conceal civil number in invitation creation dialog.
invitations.require_user_details
Render "Show user details" button in invitation creation form.
invitations.show_tax_number
Show tax number field in invitation creation form.
invitations.tax_number_required
Make tax number field mandatory in invitation creation form.
marketplace.conceal_prices
Do not render prices in order details.
marketplace.import_resources
Allow to import resources from service provider to project.
marketplace.lexis_links
Enabled LEXIS link integrations for offerings.
marketplace.show_call_management_functionality
Enabled display of call management functionality.
marketplace.show_experimental_ui_components
Enabled display of experimental or mocked components in marketplace.
openstack.hide_volume_type_selector
Allow to hide OpenStack volume type selector when instance or volume is provisioned.
openstack.show_migrations
Show OpenStack tenant migrations action and tab
project.estimated_cost
Render estimated cost column in projects list.
project.oecd_fos_2007_code
Enable OECD code.
project.show_description_in_create_dialog
Show description field in project create dialog.
project.show_end_date_in_create_dialog
Show end date field in project create dialog.
project.show_image_in_create_dialog
Show image field in project create dialog.
project.show_industry_flag
Show industry flag.
project.show_start_date_in_create_dialog
Show start date field in project create dialog.
project.show_type_in_create_dialog
Show type field in project create dialog.
rancher.volume_mount_point
Allow to select mount point for data volume when Rancher cluster is provisioned.
slurm.jobs
Render list of SLURM jobs as a separate tab in allocation details page.
support.conceal_change_request
Conceal "Change request" from a selection of issue types for non-staff/non-support users.
support.pricelist
Render marketplace plan components pricelist in support workspace.
support.shared_providers
Render overview of shared marketplace service providers in support workspace.
support.users
Render list of users in support workspace.
support.vm_type_overview
Enable VM type overview in support workspace.
telemetry.send_metrics
Send telemetry metrics.
user.disable_user_termination
Disable user termination in user workspace.
user.notifications
Enable email and webhook notifications management in user workspace.
user.preferred_language
Render preferred language column in users list.
user.show_slug
Enable display of slug field in user summary.
user.ssh_keys
Enable SSH keys management in user workspace.
General Configuration
Outline:
- General Configuration
- Introduction
- Admin dashboard configuration
- Custom templates configuration
- Local time zone configuration
Introduction
Waldur is a Django-based application, so configuration is done by modifying settings.py
file.
If you want to configure options related to Django, such as tune caches, database connection, configure custom logging, etc, please refer to Django documentation.
Please consult configuration guide to learn more.
Admin dashboard configuration
An admin dashboard supports custom links on Quick access panel. For instance, a panel below was configured with one additional link to https://waldur.com:
Configuration of custom links is stored under FLUENT_DASHBOARD_QUICK_ACCESS_LINKS
settings key and for current example has following structure:
1 2 3 4 5 6 7 8 9 |
|
Here is a short description of link parameters:
Name | Type | Required | Description |
---|---|---|---|
description | string | No | Tool tip on the link |
external | boolean | No | Specifies whether additional icon indicating an external URL has to be added |
url | URL | Yes | A URL of the link |
title | string | Yes | A title of the generated link |
attrs | dict | No | A dictionary of anchor attributes to be added to generated element |
It is also possible to omit optional fields and add links by specifying only a title and a URL to the generated link.
1 2 3 4 |
|
Custom templates configuration
To overwrite default templates you should use django-dbtemplates. It allows creation of templates through /admin
.
Local time zone configuration
Set TIME_ZONE
setting in /etc/waldur/override.conf.py
to use local time zone. By default it is set to UTC. See the list of time zones for possible options.
Configuration of the Google Calendar
Overriding notification templates via admin panel
An admin can override(edit the content) the templates of notifications with the following sequence of actions:
-
Go to admin panel (e.g.
http://localhost:8080/admin/
) -
Open Templates:
Utilities
->Database templates
->Templates
- Click on
Add template
on the right side.
-
Enter the path to the template file into the
Name
input field as shown below.The name should have a
<waldur_application_name>/<event_name>_<postfix>.<extension>
format, where<postfix>
can be eithermessage
orsubject
, and<extension>
- eithertxt
orhtml
.You can find a list of all notification templates here
- Scroll down and click on
Save and continue editing
and you should have the content of the template loaded automatically
- Edit the
Content
field as you like andSave
the changes.
Notifications
WALDUR_CORE.STRUCTURE
structure.change_email_request
A notification sent out when an email change is requested. Recipient is the old email address.
Templates
1 |
|
1 |
|
1 |
|
structure.notifications_profile_changes_operator
A notification sent out to notify about profile changes. The recipients are Waldur operators.
Templates
1 |
|
1 2 3 4 5 6 7 8 9 10 |
|
1 2 3 4 5 6 7 8 9 10 |
|
structure.structure_role_granted
A notification sent out when a role is granted. The recipient is the user who received the role.
Templates
1 |
|
1 |
|
1 |
|
WALDUR_CORE.USERS
users.invitation_approved
A notification sent to notify the user that his invitation has been approved. The recipient is the user who's being invited.
Templates
1 |
|
1 2 3 4 5 6 7 8 9 10 11 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
|
users.invitation_created
A notification sent to the user so that he can accept it and receive permissions. The recipient is the user who's being invited.
Templates
1 2 3 4 5 |
|
1 2 3 4 5 6 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
|
users.invitation_expired
A notification sent out to notify the user that his invitation has expired. The recipient is the user who's being invited.
Templates
1 |
|
1 2 3 4 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
users.invitation_rejected
A notification sent to notify the user that his invitation has been rejected. The recipient is the user who's being invited.
Templates
1 |
|
1 2 3 4 5 6 7 8 9 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
|
users.invitation_requested
A notification sent to staff users so that they can approve or reject invitation. The recipients are active staff users.
Templates
1 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 |
|
users.permission_request_submitted
A notification sent out to notify about submitted permission request. The recipients are active staff users or customer owners.
Templates
1 |
|
1 2 3 4 5 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
|
WALDUR_MASTERMIND.BOOKING
booking.notification
A notification sent out to notify about upcoming bookings. The recipients are users who have upcoming bookings.
Templates
1 |
|
1 2 3 4 5 6 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
|
WALDUR_MASTERMIND.INVOICES
invoices.notification
A notification of invoice. The recipients are organization owners.
Templates
1 |
|
1 2 3 4 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
invoices.upcoming_ends_notification
A notification about upcoming contract ending. The recipients are organization owners.
Templates
1 |
|
1 2 3 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
WALDUR_MASTERMIND.MARKETPLACE
marketplace.marketplace_resource_create_failed
A notification of a failed resource creation
Templates
1 |
|
1 2 3 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
marketplace.marketplace_resource_create_succeeded
A notification of a successful resource creation
Templates
1 |
|
1 2 3 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
marketplace.marketplace_resource_terminate_failed
A notification of a failed resource termination
Templates
1 |
|
1 2 3 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
marketplace.marketplace_resource_terminate_succeeded
A notification of a successful resource termination
Templates
1 |
|
1 2 3 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
marketplace.marketplace_resource_termination_scheduled
A notification of a scheduled resource termination. The recipients are project administrators and managers
Templates
1 |
|
1 2 3 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
|
marketplace.marketplace_resource_termination_scheduled_staff
A notification of a resource termination. The recipients are project administrators and managers.
Templates
1 |
|
1 2 3 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
|
marketplace.marketplace_resource_update_failed
A notification of failed resource update
Templates
1 |
|
1 2 3 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
marketplace.marketplace_resource_update_limits_failed
A notification of failed resource limits update
Templates
1 |
|
1 2 3 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
marketplace.marketplace_resource_update_limits_succeeded
A notification of a successful resource limit update. The recipients are all the users in the project.
Templates
1 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 |
|
marketplace.marketplace_resource_update_succeeded
A notification of a successful resource update. The recipients are all the users in the project.
Templates
1 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 |
|
marketplace.notification_about_project_ending
A notification about project ending. The recipients are project managers and customer owners.
Templates
1 |
|
1 2 3 4 5 6 7 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
|
marketplace.notification_about_resource_ending
A notification about resource ending. The recipients are project managers and customer owners.
Templates
1 |
|
1 2 3 4 5 6 7 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
|
marketplace.notification_about_stale_resources
A notification about stale resources. The recipients are organization owners.
Templates
1 |
|
1 2 3 4 5 6 7 8 9 10 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
|
marketplace.notification_usages
A notification about usages. The recipients are organization owners.
Templates
1 |
|
1 2 3 4 5 6 7 8 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 |
|
marketplace.notify_consumer_about_pending_order
A notification for consumer about pending order. The recipients are users that have permissions to approve the order.
Templates
1 |
|
1 2 3 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
marketplace.notify_provider_about_pending_order
A notification for provider about pending order. The recipients are users that have permissions to approve the order.
Templates
1 |
|
1 2 3 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
WALDUR_RANCHER
rancher.notification_create_user
A notification for created rancher user. The recipients is the user who requested the creation.
Templates
1 |
|
1 2 3 4 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
|
WALDUR_MASTERMIND.MARKETPLACE_REMOTE
marketplace_remote.notification_about_pending_project_updates
A notification about pending project updates. The recipients are customer owners
Templates
1 |
|
1 2 3 4 5 6 7 8 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
|
marketplace_remote.notification_about_project_details_update
A notification about project details update. The recipients the user who requested project details update and the user that reviewed it.
Templates
1 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 |
|
marketplace_policy.notification_about_project_cost_exceeded_limit
Notification about project cost exceeded limit. The recipients are all customer owners of the project.
Templates
1 |
|
1 2 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
WALDUR_MASTERMIND.SUPPORT
support.description
A notification used for issue creation.
Templates
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
support.notification_comment_added
Notification about a new comment in the issue. The recipient is issue caller.
Templates
1 2 3 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
|
1 |
|
support.notification_comment_updated
Notification about an update in the issue comment. The recipient is issue caller.
Templates
1 2 3 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
|
1 |
|
support.notification_issue_feedback
Notification about a feedback related to the issue. The recipient is issue caller.
Templates
1 2 3 4 5 6 7 8 9 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 |
|
1 |
|
support.notification_issue_updated
Notification about an update in the issue. The recipient is issue caller.
Templates
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 |
|
1 |
|
support.summary
A notification used for issue creation.
Templates
1 |
|
Message templates
waldur_core.logging
email.html (waldur_core.logging)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
waldur_core.structure
notifications_profile_changes_operator_subject.txt (waldur_core.structure)
1 |
|
notifications_profile_changes.html (waldur_core.structure)
1 2 3 4 5 |
|
change_email_request_subject.txt (waldur_core.structure)
1 |
|
notifications_profile_changes_operator_message.html (waldur_core.structure)
1 2 3 4 5 6 7 8 9 10 |
|
structure_role_granted_message.txt (waldur_core.structure)
1 |
|
structure_role_granted_subject.txt (waldur_core.structure)
1 |
|
change_email_request_message.html (waldur_core.structure)
1 |
|
change_email_request_message.txt (waldur_core.structure)
1 |
|
notifications_profile_changes_operator_message.txt (waldur_core.structure)
1 2 3 4 5 6 7 8 9 10 |
|
structure_role_granted_message.html (waldur_core.structure)
1 |
|
waldur_core.users
invitation_approved_subject.txt (waldur_core.users)
1 |
|
invitation_created_message.html (waldur_core.users)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
|
permission_request_submitted_message.html (waldur_core.users)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
|
invitation_approved_message.txt (waldur_core.users)
1 2 3 4 5 6 7 8 9 10 11 |
|
invitation_created_message.txt (waldur_core.users)
1 2 3 4 5 6 |
|
invitation_expired_message.html (waldur_core.users)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
invitation_approved_message.html (waldur_core.users)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
|
invitation_expired_subject.txt (waldur_core.users)
1 |
|
invitation_expired_message.txt (waldur_core.users)
1 2 3 4 |
|
invitation_rejected_message.txt (waldur_core.users)
1 2 3 4 5 6 7 8 9 |
|
invitation_rejected_subject.txt (waldur_core.users)
1 |
|
invitation_created_subject.txt (waldur_core.users)
1 2 3 4 5 |
|
permission_request_submitted_subject.txt (waldur_core.users)
1 |
|
invitation_requested_message.txt (waldur_core.users)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 |
|
invitation_rejected_message.html (waldur_core.users)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
|
permission_request_submitted_message.txt (waldur_core.users)
1 2 3 4 5 |
|
invitation_requested_message.html (waldur_core.users)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 |
|
invitation_requested_subject.txt (waldur_core.users)
1 |
|
waldur_mastermind.booking
notification_message.txt (waldur_mastermind.booking)
1 2 3 4 5 6 |
|
notification_message.html (waldur_mastermind.booking)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
|
notification_subject.txt (waldur_mastermind.booking)
1 |
|
waldur_mastermind.invoices
monthly_invoicing_reports.html (waldur_mastermind.invoices)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 |
|
report_body.txt (waldur_mastermind.invoices)
1 |
|
invoice.html (waldur_mastermind.invoices)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 |
|
notification_message.txt (waldur_mastermind.invoices)
1 2 3 4 |
|
upcoming_ends_notification_message.txt (waldur_mastermind.invoices)
1 2 3 |
|
upcoming_ends_notification_subject.txt (waldur_mastermind.invoices)
1 |
|
report_subject.txt (waldur_mastermind.invoices)
1 |
|
notification_message.html (waldur_mastermind.invoices)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
upcoming_ends_notification_message.html (waldur_mastermind.invoices)
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
notification_subject.txt (waldur_mastermind.invoices)
1 |
|
waldur_mastermind.marketplace
notification_about_project_ending_subject.txt (waldur_mastermind.marketplace)
1 |
|
marketplace_resource_update_limits_succeeded_message.txt (waldur_mastermind.marketplace)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
marketplace_resource_update_limits_succeeded_subject.txt (waldur_mastermind.marketplace)
1 |
|
notification_about_stale_resources_message.txt (waldur_mastermind.marketplace)
1 2 3 4 5 6 7 8 9 10 |
|
marketplace_plan_template.txt (waldur_mastermind.marketplace)
1 2 3 |
|
notification_usages_message.txt (waldur_mastermind.marketplace)
1 2 3 4 5 6 7 8 |
|
notify_consumer_about_pending_order_subject.txt (waldur_mastermind.marketplace)
1 |
|
marketplace_resource_termination_scheduled_staff_message.html (waldur_mastermind.marketplace)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
|
marketplace_resource_update_succeeded_message.html (waldur_mastermind.marketplace)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 |
|
marketplace_resource_update_failed_subject.txt (waldur_mastermind.marketplace)
1 |
|
notify_provider_about_pending_order_message.html (waldur_mastermind.marketplace)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
marketplace_resource_terminate_failed_subject.txt (waldur_mastermind.marketplace)
1 |
|
marketplace_resource_update_succeeded_message.txt (waldur_mastermind.marketplace)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
|
marketplace_resource_update_failed_message.txt (waldur_mastermind.marketplace)
1 2 3 |
|
notification_about_stale_resources_message.html (waldur_mastermind.marketplace)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
|
marketplace_resource_create_failed_message.html (waldur_mastermind.marketplace)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
notify_consumer_about_pending_order_message.txt (waldur_mastermind.marketplace)
1 2 3 |
|
marketplace_resource_create_succeeded_message.html (waldur_mastermind.marketplace)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
marketplace_resource_update_limits_failed_message.html (waldur_mastermind.marketplace)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
marketplace_resource_update_limits_succeeded_message.html (waldur_mastermind.marketplace)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 |
|
marketplace_resource_update_failed_message.html (waldur_mastermind.marketplace)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
notification_about_resource_ending_message.txt (waldur_mastermind.marketplace)
1 2 3 4 5 6 7 |
|
notification_about_project_ending_message.html (waldur_mastermind.marketplace)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
|
marketplace_resource_create_failed_subject.txt (waldur_mastermind.marketplace)
1 |
|
marketplace_resource_update_limits_failed_subject.txt (waldur_mastermind.marketplace)
1 |
|
marketplace_resource_terminate_failed_message.html (waldur_mastermind.marketplace)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
notification_usages_message.html (waldur_mastermind.marketplace)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 |
|
marketplace_resource_terminate_succeeded_message.html (waldur_mastermind.marketplace)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
marketplace_resource_termination_scheduled_staff_subject.txt (waldur_mastermind.marketplace)
1 |
|
notification_about_stale_resources_subject.txt (waldur_mastermind.marketplace)
1 |
|
notify_provider_about_pending_order_subject.txt (waldur_mastermind.marketplace)
1 |
|
marketplace_resource_terminate_succeeded_subject.txt (waldur_mastermind.marketplace)
1 |
|
marketplace_resource_termination_scheduled_message.txt (waldur_mastermind.marketplace)
1 2 3 |
|
notification_about_resource_ending_message.html (waldur_mastermind.marketplace)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
|
notification_about_project_ending_message.txt (waldur_mastermind.marketplace)
1 2 3 4 5 6 7 |
|
notification_about_resource_ending_subject.txt (waldur_mastermind.marketplace)
1 |
|
marketplace_resource_update_succeeded_subject.txt (waldur_mastermind.marketplace)
1 |
|
marketplace_resource_update_limits_failed_message.txt (waldur_mastermind.marketplace)
1 2 3 |
|
marketplace_resource_termination_scheduled_subject.txt (waldur_mastermind.marketplace)
1 |
|
notify_consumer_about_pending_order_message.html (waldur_mastermind.marketplace)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
marketplace_resource_terminate_failed_message.txt (waldur_mastermind.marketplace)
1 2 3 |
|
marketplace_resource_termination_scheduled_message.html (waldur_mastermind.marketplace)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
|
marketplace_resource_create_failed_message.txt (waldur_mastermind.marketplace)
1 2 3 |
|
marketplace_resource_termination_scheduled_staff_message.txt (waldur_mastermind.marketplace)
1 2 3 |
|
marketplace_resource_create_succeeded_subject.txt (waldur_mastermind.marketplace)
1 |
|
marketplace_resource_terminate_succeeded_message.txt (waldur_mastermind.marketplace)
1 2 3 |
|
notify_provider_about_pending_order_message.txt (waldur_mastermind.marketplace)
1 2 3 |
|
marketplace_resource_create_succeeded_message.txt (waldur_mastermind.marketplace)
1 2 3 |
|
notification_usages_subject.txt (waldur_mastermind.marketplace)
1 |
|
waldur_mastermind.marketplace_remote
notification_about_pending_project_updates_message.txt (waldur_mastermind.marketplace_remote)
1 2 3 4 5 6 7 8 |
|
notification_about_pending_project_updates_subject.txt (waldur_mastermind.marketplace_remote)
1 |
|
notification_about_project_details_update_message.txt (waldur_mastermind.marketplace_remote)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 |
|
notification_about_project_details_update_message.html (waldur_mastermind.marketplace_remote)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 |
|
notification_about_pending_project_updates_message.html (waldur_mastermind.marketplace_remote)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
|
notification_about_project_details_update_subject.txt (waldur_mastermind.marketplace_remote)
1 |
|
waldur_mastermind.marketplace_support
terminate_resource_template.txt (waldur_mastermind.marketplace_support)
1 2 3 |
|
update_resource_template.txt (waldur_mastermind.marketplace_support)
1 2 3 |
|
create_resource_template.txt (waldur_mastermind.marketplace_support)
1 2 3 4 5 6 7 8 9 |
|
update_limits_template.txt (waldur_mastermind.marketplace_support)
1 2 3 4 |
|
waldur_mastermind.support
notification_comment_updated.txt (waldur_mastermind.support)
1 2 3 |
|
notification_issue_feedback.txt (waldur_mastermind.support)
1 2 3 4 5 6 7 8 9 |
|
description.txt (waldur_mastermind.support)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
summary.txt (waldur_mastermind.support)
1 |
|
notification_issue_updated_subject.txt (waldur_mastermind.support)
1 |
|
notification_comment_added.html (waldur_mastermind.support)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
|
notification_issue_updated.html (waldur_mastermind.support)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 |
|
notification_comment_added.txt (waldur_mastermind.support)
1 2 3 |
|
notification_issue_feedback_subject.txt (waldur_mastermind.support)
1 |
|
notification_issue_feedback.html (waldur_mastermind.support)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 |
|
notification_comment_added_subject.txt (waldur_mastermind.support)
1 |
|
notification_issue_updated.txt (waldur_mastermind.support)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
|
notification_comment_updated.html (waldur_mastermind.support)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
|
notification_comment_updated_subject.txt (waldur_mastermind.support)
1 |
|
Ended: Mastermind configuration
Providers ↵
Azure
Warning
Documentation is in progress. Plugin development is in progress.
Setting up Tenant
https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-create-new-tenant
Setting up a Client
https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app
Add permissions
Make sure that client is able to perform operations on the different resources.
Collecting Azure credentials for Waldur
You need to provide following Azure credentials to Waldur: subscription ID, tenant ID, client ID and client secret.
Get Subscription ID
- Login into your Azure account.
- Select Subscriptions in the left sidebar.
- Select whichever subscription is needed.
- Click on Overview.
- Copy the Subscription ID.
Get Tenant ID
- Login into your Azure account.
- Select Azure Active Directory in the left sidebar.
- Click Properties.
- Copy the Directory ID.
Get Client ID
- Login into your Azure account.
- Select Azure Active Directory in the left sidebar.
- Click Enterprise applications.
- Click All applications.
- Select the application which you have created.
- Click Properties.
- Copy the Application ID.
Get Client secret
- Login into your Azure account.
- Select Azure Active Directory in the left sidebar.
- Click App registrations.
- Select the application which you have created.
- Click on All settings.
- Click on Keys.
- Type Key description and select the Duration.
- Click save.
- Copy and store the key value. You won’t be able to retrieve it after you leave this page.
Custom scripts
Custom scripts
is a type of plugin that allows defining custom scripts that are executed
at different lifecycle events of the resource. The scripts are executed in one time containers.
Depending on the deployment type, it can be either a docker container for docker-compose-based, or
Kubernetes Jobs for Helm-based deployments.
The following lifecycle events are supported:
- Creation;
- Update - change of plans or limits;
- Termination;
- Regular updates - executed once per hour, aka pull script.
Script output format
It is possible to control certain aspects of resource management with outputs of the custom scripts. Below we list currently supported conventions and their impact.
Creation script
You can set the the backend_id of the created resource by passing a single string as the last line of the output.
1 2 3 |
|
If you want to save additional metadata, then last line of output should consist of 2 strings:
- ID of the created resource that will be saved as backend_id;
- Base64 encoded metadata object.
1 2 3 4 5 6 |
|
Regular updates script
The script for regular updates allows to update usage information as well as provide updates of reporting. In all cases the last line should include a base64-encoded string containing a dictionary with keywords:
- "usages" for usage reporting;
- "report" for updating resource report.
Examples of Python-based scripts are:
1 2 3 4 5 6 7 8 9 10 11 |
|
1 2 3 4 5 6 7 8 9 10 11 |
|
MOAB
MOAB is a scheduling engine for HPC centers from Adaptive Computing.
Waldur implementation of support for MOAB is done via the Waldur site agent.
OpenStack (Tenant)
Requirements for OpenStack (Tenant)
OpenStack versions tested:
- Queens
- Rocky
- Stein
- Train
- Ussuri
- Victoria
In order to integrate an OpenStack-based cloud as a shared provider, the following data is required:
- URL of Keystone's public endpoint (v3).
- Access to public interfaces of Keystone, Nova, Cinder, Neutron and Glance should be opened to Waldur MasterMind server.
- Admin credentials (username/password) as well as domain name (in case non-default domain is used).
- External network UUID - the network will be by default connected to all created OpenStack Projects (Tenants).
Advanced settings
It's possible to override some settings for OpenStack in MasterMind admin interface. To do that, please go to Waldur MasterMind Admin interface with a staff account.
Go to Structure → Shared provider settings and select the one you want to update.
Define specific customisation options. To add an option select append on item block under the object tree. Most typical are:
- external_network_id – external network to connect to when creating a VPC from this provider.
- access_url - a URL to access OpenStack Horizon dashboard from a public network. Typically a reverse proxy URL in production deployments.
- flavor_exclude_regex - flavors matching this regex expression will not be pulled from the backend.
- dns_nameservers - default value for new subnets DNS name servers. Should be defined as list.
- create_ha_routers - create highly available Neutron routers when creating Tenants.
Support for Organization specific OpenStack networks
You can provide specific external network for all OpenStack Tenants created by Organiztion by providing external network UUIDs in Organization configuration in Waldur Mastermind admin portal.
Remote Offering
Warning
Documentation is in progress. Plugin development is in progress.
Introduction
It is possible to import into a Waldur offerings from a remote Waldur.
Pre-requisites
- An organization in the remote Waldur, which will contain requests and projects from the local Waldur.
- Account with owner role that will be used for integration.
- Access to APIs of remote Waldur.
High level process
- In local Waldur, make sure that you have a service provider organization available.
- Click on "Import offering".
- Input remote Waldur API and authentication token.
- Select the remote organization and offering to be imported.
- Review and activate the offering.
eduTEAMS account SYNC
In case both local and remote Waldurs are relying on a common set of identities from eduTEAMS, it is possible to configure synchronisation of the identities as well, i.e. when a resource is provisioned in a remote Waldur, local accounts from organization and project are pushed and mapped to the remote project.
Note
For this to work, remote Waldur must be integrated with eduTEAMS registry and integration user must have
identity_manager
role.
Remote offering actions
Remote offering actions are available in the integration section of the offering edit page.
SLURM provider
SLURM plugin enables sharing of access to a SLURM cluster. SLURM is a scheduling system used typically for managing High-performance clusters. Waldur allows to share access by creating Slurm accounts and managing permission rights of users.
Configure Waldur SLURM plugin
By default, Waldur creates a hierarchical account structure in SLURM, where:
- Organization gets an account under a default account, defined when configuring SLURM service offering;
- Each project is created as a an allocation, which is a child of organization's account.
- Each resource created in Waldur (aka SLURM Allocation) gets its own SLURM account with project account as a parent.
These accounts get standard prefixes along with unique values and user provided input. It is possible to customize prefixes in Waldur configuration. Check WALDUR_SLURM variables in Waldur configuration guide.
Add SLURM provider
To add SLURM as a provider to Waldur, you will need the following information:
- SSH host address to a node, from where SLURM commands could be executed.
- Username that has Slurm operator role. Operator is needed as Waldur dynamically creates accounts based on user's choice of FreeIPA account.
- Waldur public key must be added as authorized_key for the operator's username.
- Slurm login node must be configured to authenticate users coming from FreeIPA connected to Waldur.
SLURM auto-provisioning hooks
It is possible to streamline creation of SLURM allocations for new users based on affiliation of a user profile. Configuration settings are described in Waldur configuration guide under WALDUR_HPC settings.
The logic is as follows:
- Once a user is created (e.g. via eduGAIN login), user's affiliation and email are checked to see if user belongs to internal or external organization.
- If so, a project is created for the user in a corresponding organization.
- For users belonging to internal organization, SLURM request is pre-filled and created using account limits of internal organizations.
- For users belonging to external organization, SLURM request is pre-filled only - it would require a manual confirmation from the organization owner of the external organization to be provisioned. Default limits of SLURM apply.
Configure SLURM cluster
Waldur might work out of the box with most of the reasonably modern deployments of SLURM, which have accounting enabled and limits enforced.
Please refer to SLURM documentation for details:
We provide a snapshot of instructions for the convenience of the reader.
Add SLURM cluster
SLURM accounting plugin assumes that at least one cluster is configured. For example:
1 |
|
Enforce SLURM accounting limits
In order to enforce limits set on associations and QoS, please modify slurm.conf:
1 |
|
Please note, that when AccountingStorageEnforce is changed, a restart of the slurmctld daemon is required (not just a scontrol reconfig
):
1 |
|
Enable SLURM Multi Priority plugin
In order to enable ordering for the queue of jobs waiting to be scheduled, please modify slurm.conf:
1 |
|
When slurm.conf is changed, you should reload configuration:
1 |
|
Waldur Site Agent
Agent for Mastermind integration with a provider's site. The main purpose of the agent is data syncronization between Waldur and an application (for example SLURM or MOAB cluster). The agent uses order-related information from Waldur to manage accounts in the site and accounting-related info from the site (backend) to update usage data in Waldur. For now, the agent supports only SLURM and MOAB clusters as a site.
Architecture
Agent is a stateless application, which is deployed on a machine having access to a backend data. It consists of three sub-applications:
agent-order-process
, which fetches ordering data from Waldur and updates a state of a backend correspondingly; (e.g. creates/updates/deletes SLURM accounts);agent-report
, which reports computing usage and limits info from a backend to Waldur (e.g. update of resource usages);agent-membership-sync
, which syncs membership info between Waldur and a backend (e.g. adds users to a SLURM allocation).
Integration with Waldur
For this, the agent uses Waldur client
based on Python and REST communication with Waldur backend.
Agent-order-process
application pulls data of orders created
in Waldur and creates/updates/removes backend resources based on this info.
Agent-report
fetches usage data pushes it to Waldur.
Agent-membership-sync
fetches associations from
a backend and syncronizes it with remote ones.
Integration with the site
SLURM cluster
The agent relies on SLURM command line utilities (e.g. sacct
and sacctmgr
)
and should run on a headnode of the SLURM cluster.
MOAB cluster
The agent relies on MOAB command line utilities (e.g. mam-list-accounts
and mam-create-account
)
and should run on a headnode of the MOAB cluster as a root user.
Agent configuration
The application supports the following CLI arguments:
-m
,--mode
- mode of agent; supported values:order_process
,report
andmembership_sync
; default isorder_process
.-c
,--config-file
- path to the config file with provider settings.
Optional environment variables:
WALDUR_SITE_AGENT_ORDER_PROCESS_PERIOD_MINUTES
- trigger period fororder_process
mode in minutes (default is 5);WALDUR_SITE_AGENT_REPORT_PERIOD_MINUTES
- trigger period forreport
mode in minutes (default is 30);WALDUR_SITE_AGENT_MEMBERSHIP_SYNC_PERIOD_MINUTES
- trigger period formembership_sync
mode in minutes (default is 5).REQUESTS_VERIFY_SSL
- flag for SSL verification for Waldur client, default istrue
.SENTRY_ENVIRONMENT
- name of the Sentry environment.
The primary config for the agent is a waldur-site-agent-config.yaml
.
Using it, the agent can serve several offerings
and setup backend-related data, for example computing component settings.
File example and reference.
NB: for MOAB, the only acceptable component is deposit
.
All other specified components are ignored by the agent.
Deployment
A user should deploy 3 separate instances of the agent. The first one (called agent-order-process) fetches data from Waldur with further processing, the second one (called agent-report) sends usage data from the backend to Waldur and the third one syncs membership information between Waldur and the backend. All the instances must be configured with CLI variables and provider config file.
To deploy them, you need to setup and start the systemd services.
Prerequisite: offering configuration in Waldur
SLURM and MOAB
The agents require existing offering data in Waldur. As a service provider owner, you should create an offering in the marketplace:
- Go to
Service Provider
section of the organization and open offering creation menu - Input a name, choose a category, select
SLURM remote allocation
from the drop-down list on the bottom and clickCreate
button
- Open the offering page and create a plan in the
Accounting
section: clickAdd plan
and input the necessary details - Go to
Integration
section, clickShow integration steps
and ensure they are completed within your SLURM/MOAB cluster.
Setup
Firstly, install the waldur-site-agent
module:
1 |
|
Secondly, create the provider config file and adjust the content for your needs.
1 |
|
Please use the waldur_site_load_components
command
to load computing components into Waldur.
1 |
|
Thirdly, put systemd unit and provider config files to the corresponding locations.
-
agent-order-process systemd unit: waldur-agent-order-process.service
-
agent-report systemd unit: waldur-agent-report.service
-
agent-membership-sync systemd unit: waldur-agent-membership-sync.service
1 2 3 4 5 6 7 8 |
|
After these preparation steps, run the following script to apply the changes.
1 2 3 4 5 6 7 |
|
Older systemd versions
If you want to deploy the agents on a machine with systemd revision older than 240, you should use files with legacy configuration:
- systemd legacy unit file for agent-pull: waldur-site-agent-pull-legacy.service
- systemd legacy unit file for agent-push: waldur-site-agent-push-legacy.service
1 2 3 4 5 6 |
|
Provider config file reference
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 |
|
Ended: Providers
Rke2 setup ↵
Waldur on RKE2
RKE2 installation and setup
To install Waldur on top of RKE2 you need to:
-
Install Ansible with version >= 2.10 and ensure python3 is installed.
-
Download this repository
-
At least 3 nodes with minimal requirements for Kubernetes nodes
1 2 3
8GB RAM 4 vCPU 30GB for system volume and a dedicated 60GB for storage (Longhorn)
-
Install
kubernetes.core
collection from ansible galaxy.1 2 3 4 5 6 7 8
ansible-galaxy collection install kubernetes.core ansible-galaxy collection install ansible.posix # or curl -L -o ansible-galaxy/kubernetes-core-2.3.2.tar.gz --create-dirs https://galaxy.ansible.com/download/kubernetes-core-2.3.2.tar.gz ansible-galaxy collection install ansible-galaxy/kubernetes-core-2.3.2.tar.gz curl -L -o ansible-galaxy/ansible-posix-1.4.0.tar.gz https://galaxy.ansible.com/download/ansible-posix-1.4.0.tar.gz ansible-galaxy collection install ansible-galaxy/ansible-posix-1.4.0.tar.gz
-
Adjust variables in
ansible-config/rke2_vars
file -
(Optional) Run the playbook to setup infrastructure (Kubernetes and Longhorn):
1 2
cd ansible-config ansible-playbook -D -i rke2_inventory install-infrastructure.yaml
-
Run the playbook to install Waldur and dependencies:
1 2
cd ansible-config ansible-playbook -D -i rke2_inventory install-applications.yaml
You can check Waldur release installation with the following steps:
-
ssh to a node from inventory with
initial_server=true
and check all the pods from the default namespace:1 2
export KUBECONFIG=/etc/rancher/rke2/rke2.yaml kubectl get pods -n default
If you run Waldur in a different namespace, please adjust the value of the -n
option in the last command above.
Add admin ssh keys
- Setup
admin_keys
andrevoked_admin_keys
vars in theansible-config/rke2_vars
file -
Run the corresponding playbook
1 2
cd ansible-config ansible-playbook -D -i rke2_inventory add-ssh-keys.yml
Add haproxy load balancer
- Setup
haproxy_stats_password
var in theansible-config/rke2_vars
file -
Run the corresponding playbook
1 2
cd ansible-config ansible-playbook -D -i rke2_inventory add-haproxy-host.yml
Waldur Helm configuration
A user can override default settings for Waldur Helm. The ansible-config/waldur/values.yaml
is the main settings file. Additional configuration features files (e.g. for SAML2, whitelabeling, bootstrapping, etc.) can be included by placing into corresponding subdirectories of ansible-config/waldur/
folder. The paths to the subdirectories should be specified in ansible-config/waldur/values.yaml
, e.g. waldur.saml2.dir
value.
Waldur Helm configuration is described in the public docs; example values.yaml
file: link, example additional files: link.
Update of Waldur
To update Waldur user needs to execute the corresponding playbook:
1 2 |
|
Update of Waldur dependencies
To update Waldur dependencies, a user should:
- Setup the desired components for update in
ansible-config/rke2_vars
file, e.g. setsetup_postgresql
toyes
in case of PostgreSQL Helm chart update. NB: please, don't change chart versions manually, it can cause failure of Waldur application -
Run the corresponding playbook:
1 2
cd ansible-config ansible-playbook -D -i rke2_inventory install-applications.yaml
Example of changes in ansible-config/rke2_vars
file:
1 2 3 4 5 6 7 8 9 |
|
With this setup, the playbook will update PostgreSQL release only. If the user wants to update RabbitMQ too, they should set setup_rabbitmq: yes
Waldur log fetching
To get logs from Waldur containers, a users needs to connect to one of the RKE2 nodes:
1 |
|
A node IP should be chosen from the inventory file (e.g. rke2_inventory
).
In the node's shell, the user should run the following to setup Kubernetes client:
1 |
|
After this, the user can get Waldur API logs:
1 |
|
Same works for Celery worker:
1 |
|
Note: if you use a non-default namespace for Waldur release, please change the value for -n
option in the aforementioned command
Setup SSL certificates
NB: do not forget to set apiScheme
ans homeportScheme
to https
in ansible-config/waldur/values.yaml
Custom certificates
To setup the SSL certificates, please do the following steps:
- Copy the certificate and key to the
ansible-config/waldur/tls
directory. NB: key must be namedtls.key
and cert itself -tls.crt
- In
ansible-config/waldur/values.yaml
, setingress.tls.source
tosecret
- Update Waldur release
Let's Encrypt
To setup SSL certificates using Let's Encrypt, please do the following steps:
- In
ansible-config/rke2_vars
, setsetup_lets_encrypt
toyes
- In
ansible-config/waldur/values.yaml
, setingress.tls.source
toletsEncrypt
- Install Let's Encrypt via
install-applications.yaml
playbook
1 |
|
Enable K8s dashboard
Make sure that K8s dashboard is deployed. Login to one of the K8s nodes.
1 2 3 4 5 |
|
K8s dashboard should now be accessible on port 8001 in that node -- or load balancer node on port 8001 if configured.
Recover data from DB backup
In order to apply an existing backup to database, a corresponding playbook exists.
NB:
- This operation drops an existing database, creates an empty one and applies the pre-created backup
- During restoration process, the site will be unavailable
During execution, you will be asked about backup name. You should input it in a correct way. Example of running playbook:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
|
After this, you should input one of the following lines:
- backup-2022-12-01-05-00.sql.gz
- backup-2022-11-30-05-00.sql.gz
- backup-2022-11-29-05-00.sql.gz
- backup-2022-11-28-16-30.sql.gz
- backup-2022-11-28-16-28.sql.gz
Otherwise, the entire process will fail, but the site and database with old data will be still available.
To start the process, please, execute the following line in the machine connected to RKE2 nodes:
1 |
|
Ended: Rke2 setup
Ended: Admin guide
Developer guide ↵
Developer documentation
- Installation from source code
- Workflow
- Settings policy
- Permissions
- Managed entities
- Resource actions
- Logging
- Background processing
- Quotas
- Tasks and executors
- How to write serializers
- How to write views
- How to write tests
- How to write docs
- How to add a new language
- Internationalization
- Plugins
- Events
- Models
- Templates
Ad-hoc scripts
This section describes different ad-hoc scripts used by Waldur developers.
Usage-related scripts
Restore CPU/GPU/RAM usages for a month
Sometimes, Waldur can have issues with data correctness. They can be caused by different circumstansies, e.g. problems with data syncronization between Waldur backend and service provider software. In order to resolve these issues, a user can restore usage data with restore_usages.py script.
Generate openmetrics file with usages for several months
If a user needs to create openmetrics file with usages, e.g. for historical data backfilling in Prometheus, the generate_openmetrics_usages.py can be used.
Prolong expired projects
If a user needs to prolong an expired project with remote resources, this script should be used. It can:
- automatically detect projects with pending update requests
- approve the requests
- set state OK for terminating resources both in a local Waldur and remote one
Note: the script must be executed in a local Waldur instance
Wipe tenants and all related resources from OpenStack
If a user needs to remove a tenant with all related objects (instances, volumes, backups, etc.) manually, this script should be used. It removes all the tenants with names from tenant_names
list using an OpenStack administrator project. Please, replace <main-tenant-uuid>
(line 13) with the corresponding UUID of the admin tenant in Waldur.
Import projects with slug info
A CSV-file with the following format is required:
1 2 |
|
Put this file to the /tmp/projects-info.csv
location and
execute this script with your Waldur shell.
Background processing
For executing heavier requests and performing background tasks Waldur is using Celery. Celery is a task queue that supports multiple backends for storing the tasks and results. Currently Waldur is relying on Redis backend - Redis server must be running for requests triggering background scheduling to succeed.
If you are developing on OS X and have brew installed:
1 2 |
|
Please see Redis docs for installation on other platforms.
Finite state machines
Some of the models in Waldur have a state field representing their
current condition. The state field is implemented as a finite state
machine. Both user requests and background tasks can trigger state
transition. A REST client can observe changes to the model instance
through polling the state
field of the object.
Let's take VM instance in 'offline' state. A user can request the instance to start by issuing a corresponding request over REST. This will schedule a task in Celery and transition instance status to 'starting_scheduled'. Further user requests for starting an instance will get state transition validation error. Once the background worker starts processing the queued task, it updates the Instance status to the 'starting'. On task successful completion, the state is transitioned to 'online' by the background task.
Error state of background tasks
If a background task has failed to achieve it's goal, it should transit into an error state. To propagate more information to the user each model with an FSM field should include a field for error message information - error_message. The field should be exposed via REST. Background task should update this field before transiting into an erred state.
Cleaning of the error state of the model instance should clean up also
error_message
field.
Events
Access_subnets
- access_subnet_creation_succeeded
- access_subnet_deletion_succeeded
- access_subnet_update_succeeded
Auth
- auth_logged_in_with_username
- auth_logged_out
- auth_login_failed_with_username
- token_created
- token_lifetime_updated
Call
- call_document_added
- call_document_removed
Customers
- create_of_credit_by_staff
- customer_creation_succeeded
- customer_deletion_succeeded
- customer_update_succeeded
- invoice_canceled
- invoice_created
- invoice_item_created
- invoice_item_deleted
- invoice_item_updated
- invoice_paid
- payment_added
- payment_created
- payment_removed
- reduction_of_credit
- reduction_of_credit_due_to_minimal_consumption
- set_to_zero_overdue_credit
- update_of_credit_by_staff
Invoices
- create_of_credit_by_staff
- invoice_canceled
- invoice_created
- invoice_creation_succeeded
- invoice_deletion_succeeded
- invoice_item_created
- invoice_item_deleted
- invoice_item_updated
- invoice_paid
- invoice_update_succeeded
- payment_created
- payment_removed
- reduction_of_credit
- reduction_of_credit_due_to_minimal_consumption
- set_to_zero_overdue_credit
- update_of_credit_by_staff
Payments
- payment_approval_succeeded
- payment_cancel_succeeded
- payment_creation_succeeded
Permissions
- role_granted
- role_revoked
- role_updated
Projects
- project_creation_succeeded
- project_deletion_succeeded
- project_deletion_triggered
- project_update_request_approved
- project_update_request_created
- project_update_request_rejected
- project_update_succeeded
Proposal
- proposal_canceled
- proposal_document_added
- proposal_document_removed
Providers
- marketplace_resource_create_canceled
- marketplace_resource_create_failed
- marketplace_resource_create_requested
- marketplace_resource_create_succeeded
- marketplace_resource_terminate_failed
- marketplace_resource_terminate_requested
- marketplace_resource_terminate_succeeded
- marketplace_resource_update_failed
- marketplace_resource_update_limits_failed
- marketplace_resource_update_limits_succeeded
- marketplace_resource_update_requested
- resource_robot_account_created
- resource_robot_account_deleted
- resource_robot_account_updated
Resources
- marketplace_order_approved
- marketplace_order_completed
- marketplace_order_created
- marketplace_order_failed
- marketplace_order_rejected
- marketplace_order_terminated
- marketplace_resource_create_canceled
- marketplace_resource_create_failed
- marketplace_resource_create_requested
- marketplace_resource_create_succeeded
- marketplace_resource_downscaled
- marketplace_resource_erred_on_backend
- marketplace_resource_has_been_changed
- marketplace_resource_paused
- marketplace_resource_terminate_canceled
- marketplace_resource_terminate_failed
- marketplace_resource_terminate_requested
- marketplace_resource_terminate_succeeded
- marketplace_resource_update_canceled
- marketplace_resource_update_end_date_succeeded
- marketplace_resource_update_failed
- marketplace_resource_update_limits_failed
- marketplace_resource_update_limits_succeeded
- marketplace_resource_update_requested
- marketplace_resource_update_succeeded
- openstack_floating_ip_attached
- openstack_floating_ip_connected
- openstack_floating_ip_description_updated
- openstack_floating_ip_detached
- openstack_floating_ip_disconnected
- openstack_network_cleaned
- openstack_network_created
- openstack_network_deleted
- openstack_network_imported
- openstack_network_pulled
- openstack_network_updated
- openstack_port_cleaned
- openstack_port_created
- openstack_port_deleted
- openstack_port_imported
- openstack_port_pulled
- openstack_router_updated
- openstack_security_group_cleaned
- openstack_security_group_created
- openstack_security_group_deleted
- openstack_security_group_imported
- openstack_security_group_pulled
- openstack_security_group_rule_cleaned
- openstack_security_group_rule_created
- openstack_security_group_rule_deleted
- openstack_security_group_rule_imported
- openstack_security_group_rule_updated
- openstack_security_group_updated
- openstack_server_group_cleaned
- openstack_server_group_created
- openstack_server_group_deleted
- openstack_server_group_imported
- openstack_server_group_pulled
- openstack_subnet_cleaned
- openstack_subnet_created
- openstack_subnet_deleted
- openstack_subnet_imported
- openstack_subnet_pulled
- openstack_subnet_updated
- openstack_tenant_quota_limit_updated
- resource_assign_floating_ip_failed
- resource_assign_floating_ip_scheduled
- resource_assign_floating_ip_succeeded
- resource_attach_failed
- resource_attach_scheduled
- resource_attach_succeeded
- resource_backup_schedule_activated
- resource_backup_schedule_cleaned_up
- resource_backup_schedule_created
- resource_backup_schedule_deactivated
- resource_backup_schedule_deleted
- resource_change_flavor_failed
- resource_change_flavor_scheduled
- resource_change_flavor_succeeded
- resource_creation_failed
- resource_creation_scheduled
- resource_creation_succeeded
- resource_deletion_failed
- resource_deletion_scheduled
- resource_deletion_succeeded
- resource_detach_failed
- resource_detach_scheduled
- resource_detach_succeeded
- resource_extend_failed
- resource_extend_scheduled
- resource_extend_succeeded
- resource_extend_volume_failed
- resource_extend_volume_scheduled
- resource_extend_volume_succeeded
- resource_import_succeeded
- resource_pull_failed
- resource_pull_scheduled
- resource_pull_succeeded
- resource_restart_failed
- resource_restart_scheduled
- resource_restart_succeeded
- resource_retype_failed
- resource_retype_scheduled
- resource_retype_succeeded
- resource_robot_account_created
- resource_robot_account_deleted
- resource_robot_account_updated
- resource_snapshot_schedule_activated
- resource_snapshot_schedule_cleaned_up
- resource_snapshot_schedule_created
- resource_snapshot_schedule_deactivated
- resource_snapshot_schedule_deleted
- resource_start_failed
- resource_start_scheduled
- resource_start_succeeded
- resource_stop_failed
- resource_stop_scheduled
- resource_stop_succeeded
- resource_unassign_floating_ip_failed
- resource_unassign_floating_ip_scheduled
- resource_unassign_floating_ip_succeeded
- resource_update_allowed_address_pairs_failed
- resource_update_allowed_address_pairs_scheduled
- resource_update_allowed_address_pairs_succeeded
- resource_update_floating_ips_failed
- resource_update_floating_ips_scheduled
- resource_update_floating_ips_succeeded
- resource_update_ports_failed
- resource_update_ports_scheduled
- resource_update_ports_succeeded
- resource_update_security_groups_failed
- resource_update_security_groups_scheduled
- resource_update_security_groups_succeeded
- resource_update_succeeded
Review
- review_canceled
Ssh
- ssh_key_creation_succeeded
- ssh_key_deletion_succeeded
Support
- attachment_created
- attachment_deleted
- attachment_updated
- issue_creation_succeeded
- issue_deletion_succeeded
- issue_update_succeeded
Users
- auth_logged_in_with_oauth
- auth_logged_in_with_saml2
- auth_logged_out_with_saml2
- freeipa_profile_created
- freeipa_profile_deleted
- freeipa_profile_disabled
- freeipa_profile_enabled
- marketplace_offering_user_created
- marketplace_offering_user_deleted
- marketplace_offering_user_restriction_updated
- ssh_key_creation_succeeded
- ssh_key_deletion_succeeded
- user_activated
- user_creation_succeeded
- user_deactivated
- user_deletion_succeeded
- user_details_update_succeeded
- user_has_been_created_by_staff
- user_password_updated
- user_password_updated_by_staff
- user_profile_changed
- user_update_succeeded
HomePort requirements
Overview
Homeport is a React-based application for interacting with Waldur Mastermind via browsers. It is intended for end-users as well as administrative roles.
Mobile-friendliness
All Homeport screens should be usable with mobile resolution.
Localization
All labels should be wrapped by translation tags to allow easy translations.
For details see instructions for developers.
Accessibility and WCAG compliance
Homeport is being used by human end-users and hence is developed according to the WCAG guidelines.
In particular, the following is followed:
- Static and dynamic linters for assuring that generated user interface conforms to technical requirements of WCAG (anchors, required attributes, etc).
- Usage of WCAG compliant colors in UI theme, provisioning of dark and light modes.
- Navigation is designed to be in compliance with WCAG 2.0 requirements.
- Manual testing for WCAG violations.
Add a new language for translatable models
For translating fields of some models we use django modeltranslation.
First run
To setup the database environment, after completing all migrations, execute in a console:
1 |
|
Add a new language
To populate the generated language tables with initial content, run
1 |
|
How to write docs
Documentation for sysadmins
Documentation for sysadmins should contain a description of settings that allows to setup and customize Waldur MasterMind. It should be located in wiki.
Documentation for developers
If documentation describes basic concepts that are not related to any
particular part of code it should be located in /docs
folder. All other documentation for developers should be located in code.
Tips for writing docs:
- add description for custom modules that are unique for particular plugin;
- add description to base class methods that should be implemented by other developers;
- don't add obvious comments for standard objects or parameters.
How to write serializers
Object identity
When you're writing serializer, you may want user to reliably specify particular object in API request and serialize object in API response. Basically there are six aspects to consider:
1) Consistency. We need to ensure consistent serialization format for API request and response not only within particular application, but also within whole system across different applications. 2) Reliability. We need to reliable identify object using some stable field so that value of this field would be the same even if all other fields are changed. 3) Security. We need to ensure that user has permission to get access to the object in question. Typically API renders 400 error if user specifies object he doesn't have access to in API request. On the backend side permission check should be done consistently. 4) Universality. There are generic API endpoints which accept objects from different application. 5) Performance. We need to consider how much data serializer fetches from database so that it wouldn't fetch data which is not used anyways and doesn't perform multiple queries when it's enough to issue single query. 6) Extensibility. Usually serializer does not have outside dependencies. But sometimes it makes sense to inject extra fields to the serializer defined in other application.
Therefore you may ask what is the best way to reliably and consistently identify object in API.
In terms of frontend rendering, user is usually concerned with object name. Typically we use name only as filtering parameter because names are not unique. That's why object identity is implemented via a UUID. Please note that usually we're not exposing ID in REST API in favor of UUID because it allows easy distribution of databases across multiple servers.
In order to decouple client and server we're implementing HATEOAS component of REST API. That's why usually we're using HyperlinkedRelatedField serializer, for example:
1 2 3 4 5 |
|
There are four notes here:
1) We need to specify lookup_field
explicitly because it's default
value is 'pk'.
2) We need to specify view_name
explicitly in order to avoid clash of
models names between different applications. You need to ensure that
it matches view name specified in urls.py module.
3) When debug mode is enabled, you may navigate to related objects via
hyperlinks using browsable API renderer and select related object
from the list.
4) Serialized hyperlink contains not only UUID, but also application
name and model. It allows to use serialized URL as request parameter
for generic API endpoint. Generic API works with different models
from arbitrary applications. Thus UUID alone is not enough for full
unambiguous identification of the object in this case.
Generic serializers
Typically serializer allows you to specify object related to one particular database model. However it is not always the case. For example, issue serializer allows you to specify object related to any model with quota. In this case you would need to use GenericRelatedField serializer. It is expected that related_models parameter provides a list of all valid models.
1 2 3 4 5 6 |
|
Usually get_all_models
method is implemented in base class and uses
Django application registry which provides access to all registered
models. Consider the following example:
1 2 3 4 |
|
In terms of database model reference to the resource is stored as generic foreign key, for example:
1 2 3 |
|
Secure serializers
In Waldur we're using role-based-access-control (RBAC) for restricting system access to authorized users. In terms of serializers there are two abstract base serializer classes, PermissionFieldFilteringMixin and PermissionListSerializer which allow to filter related fields. They are needed in order to constrain the list of entities that can be used as a value for the field. Consider the following example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
|
By using PermissionFieldFilteringMixin we ensure that value of project field is validated against current user so that only authorized user which has corresponding role in either project or customer is allowed to use this serializer.
High-performance serializers
Avoiding over-fetching
By default serializer renders value for all fields specified in fields parameter. However, sometimes user does not really need to transfer all fields over the network. It is especially important when you're targeting at mobile users with slow network or even regular users when serializer renders a lot of data which is thrown away by application anyways.
If you want to allow user to specify exactly and explicitly list of fields to render, you just need to use RestrictedSerializerMixin.
Avoiding under-fetching
By default Django doesn't optimize database queries to the related objects, so separate query is executed each time when related object is needed. Fortunately enough, Django provides you with powerful methods to join database queries together and cache resulting queryset in RAM using identity map, so that instead of performing multiple consequent queries to the database it's enough to issue single query.
So in order to reduce number of requests to DB your view should use
EagerLoadMixin. It is expected that corresponding serializer implements
static method eager_load
, which selects objects necessary for
serialization.
Consider the following example:
1 2 3 4 5 6 7 8 9 10 11 |
|
Extensible serializers
Usually serializer does not have outside dependencies, but sometimes it makes sense to inject extra fields to the serializer defined in other application so that it would not introduce circular dependencies. Please note that this mechanism should be used with caution as it makes harder to track dependencies.
The main idea is that instead of introducing circular dependency we're introducing extension point. This extension point is used in depending application in order to inject new fields to existing serializer.
Example of host serializer implementation:
1 2 3 4 |
|
Guest application should subscribe to pre_serializer_fields
signal and
inject additional fields. Example of signal handler implementation:
1 2 3 4 5 6 7 8 9 |
|
How to write tests
Application tests structure
Application tests should follow next structure:
-
/tests/ - folder for all application tests.
-
/tests/test_my_entity.py - file for API calls tests that are logically related to entity. Example: test calls for project CRUD + actions.
-
/tests/test_my_entity.py:MyEntityActionTest - class for tests that are related to particular endpoint. Examples: ProjectCreateTest, InstanceResizeTest.
-
/tests/unittests/ - folder for unittests of particular file.
-
/tests/unittests/test_file_name.py - file for test of classes and methods from application file "file_name". Examples: test_models.py, test_handlers.py.
-
/tests/unittests/test_file_name.py:MyClassOrFuncTest - class for test that is related to particular class or function from file. Examples: ProjectTest, ValidateServiceTypeTest.
Tips for writing tests
- cover important or complex functions and methods with unittests;
- write at least one test for a positive flow for each endpoint;
- do not write tests for actions that does not exist. If you don't support "create" action for any user there is no need to write test for that;
- use fixtures (module fixtures.py) to generate default structure.
How to override settings in unit tests
Don't manipulate django.conf.settings directly as Django won't restore the original values after such manipulations. Instead you should use standard context managers and decorators. They change a setting temporarily and revert to the original value after running the testing code. If you modify settings directly, you break test isolation by modifying global variable.
If configuration setting is not plain text or number but dictionary, and you need to update only one parameter, you should take whole dict, copy it, modify parameter, and override whole dict.
Wrong:
1 2 |
|
Right:
1 2 3 4 5 |
|
Running tests
In order to run unit tests for specific module please execute the following command. Note that you should substitute module name instead of example waldur_openstack. Also it is assumed that you've already activated virtual Python environment.
1 |
|
How to write views
View workflow
-
Filtering - filter objects that are visible to a user based on his request. Raise 404 error if object is not visible.
-
Permissions check - make sure that user has right to execute chosen action. Raise 403 error if user does not have enough permissions.
-
View validation - check object state and make sure that selected action can be executed. Raise 409 error if action cannot be executed with current object state.
-
Serializer validation - check that user's data is valid.
-
Action logic execution - do anything that should be done to execute action. For example: schedule tasks with executors, run backend tasks, save data to DB.
-
Serialization and response output - return serialized data as response.
Internationalization
Per-request internationalization is enabled by default for English and Estonian languages.
Client requests will respect the Accept-Language
.
Here are the guidelines for specifying translation strings:
- Build a proper sentence: start with a capital letter, end with a period.
Right: _('Deletion was scheduled.')
Wrong: _('deletion was scheduled')
- Use named-string interpolation instead of positional interpolation if message has several parameters.
Right: _('Operation was successfully scheduled for %(count)d instances: %(names)s.')
Wrong: _('Operation was successfully scheduled for %s instances: %s.')
- help_text, verbose_name, exception message and response message should be marked, but don't mark message template for event or alert logger.
Installation from source
Prerequisites
- Linux OS: Ubuntu or CentOS. If you use Windows, you should install Linux either via Virtualbox or Windows Subsystem for Linux.
git
redis
andhiredis
libraryvirtualenv
C
compiler and development libraries needed to build dependencies- CentOS:
gcc libffi-devel openssl-devel postgresql-devel libjpeg-devel zlib-devel python-devel xmlsec1 xz-devel
- Ubuntu:
sudo apt install git python3-pip python3-venv python3-dev gcc libffi-dev libsasl2-dev libssl-dev libpq-dev libjpeg8-dev zlib1g-dev xmlsec1 libldap2-dev liblzma-dev libxslt1-dev libxml2-dev libbz2-dev libreadline-dev libsqlite3-dev
- OS X:
brew install openssl; export CFLAGS="-I$(brew --prefix openssl)/include $CFLAGS"; export LDFLAGS="-L$(brew --prefix openssl)/lib $LDFLAGS"
Waldur MasterMind installation
Install poetry
1 |
|
Install pyenv
1 2 3 4 |
|
Get the code
1 2 |
|
Install Waldur in development mode along with dependencies
1 2 |
|
NB: If you use a machine with Apple M1 CPU, run this before:
1 2 3 4 |
|
Create and edit settings file (see 'Configuration' section for details)
1 2 |
|
Initialise PostgreSQL database
1 2 3 |
|
Add a password waldur for this user
1 2 3 |
|
Then run poetry
1 |
|
Collect static data -- static files will be copied to ./static/
in the same directory
1 |
|
- Start Waldur:
1 |
|
Configuration
Instructions are here: https://docs.waldur.com/admin-guide/mastermind-configuration/general/
Event logging
Event log entries is something an end user will see. In order to improve user experience the messages should be written in a consistent way.
Here are the guidelines for writing good log events.
- Use present perfect passive for the message.
Right: Environment %s has been created.
Wrong: Environment %s was created.
- Build a proper sentence: start with a capital letter, end with a period.
Right: Environment %s has been created.
Wrong: environment %s has been created
- Include entity names into the message string.
Right: User %s has gained role of %s in project %s.
Wrong: User has gained role in project.
- Don't include too many details into the message string.
Right: Environment %s has been updated.
Wrong: Environment has been updated with name: %s, description: %s.
- Use the name of an entity instead of its
__str__
.
Right: event_logger.info('Environment %s has been updated.', env.name)
Wrong: event_logger.info('Environment %s has been updated.', env)
- Don't put quotes around names or entity types.
Right: Environment %s has been created.
Wrong: Environment "%s" has been created.
- Don't capitalize entity types.
Right: User %s has gained role of %s in project %s.
Wrong: User %s has gained Role of %s in Project %s.
- For actions that require background processing log both start of the process and its outcome.
Success flow:
-
log
Environment %s creation has been started.
within HTTP request handler; -
log
Environment %s has been created.
at the end of background task.
Failure flow:
-
log
Environment %s creation has been started.
within HTTP request handler; -
log
Environment %s creation has failed.
at the end of background task. -
For actions that can be processed within HTTP request handler log only success.
Success flow:
log User %s has been created.
at the end of HTTP request handler.
Failure flow:
don't log anything, since most of the errors that could happen here are validation errors that would be corrected by user and then resubmitted.
Managed entities
Overview
Managed entities are entities for which Waldur's database is considered an authoritative source of information. By means of REST API a user defines the desired state of the entities. Waldur's jobs are then executed to make the backend (OpenStack, JIRA, etc) reflect the desired state as close as possible.
Since making changes to a backend can take a long time, they are done in background tasks.
Here's a proper way to deal with managed entities:
- within the scope of REST API request:
- introduce the change (create, delete or edit an entity) to the Waldur's database;
- schedule a background job passing instance id as a parameter;
-
return a positive HTTP response to the caller.
-
within the scope of background job:
-
fetch the entity being changed by its instance id;
- make sure that it is in a proper state (e.g. not being updated by another background job);
- transactionally update the its state to reflect that it is being updated;
- perform necessary calls to backend to synchronize changes from Waldur's database to that backend;
- transactionally update its state to reflect that it not being updated anymore.
Using the above flow makes it possible for user to get immediate feedback from an initial REST API call and then query state changes of the entity.
Managed entities operations flow
-
View receives request for entity change.
-
If request contains any data - view passes request to serializer for validation.
-
View extracts operations specific information from validated data and saves entity via serializer.
-
View starts executor with saved instance and operation specific information as input.
-
Executor handles entity states checks and transition.
-
Executor schedules celery tasks to perform asynchronous operations.
-
View returns response.
-
Tasks asynchronously call backend methods to perform required operation.
-
Callback tasks changes instance state after backend method execution.
Simplified schema of operations flow
View ---> Serializer ---> View ---> Executor ---> Tasks ---> Backend
Models
Structure application models
Permissions application models
Marketplace application models
Role-based access control
Introduction
Waldur authorization system determines what user can do. It consists of permissions and roles. Permission is unique string designating action to be executed. Role is named set of permissions. This functionality is implemented in waldur_core.permissions
application.
First thing to remember is to use PermissionEnum
to define permissions instead of using plain string or standalone named constant, otherwise they would not be pushed to frontend.
1 2 3 4 5 |
|
Next, let's assign that permissions to role.
1 2 3 4 5 6 |
|
Now, let's assign customer owner role to particular user and customer:
1 2 3 4 5 6 7 8 |
|
Finally, we can check whether user is allowed to create offering in particular organization.
1 2 3 4 |
|
Please note that this function accepts not only customer, but also project and offering as a scope. Consider these models as authorization aggregates. Other models, such as resources and orders, should refer to these aggregates to perform authorization check. For example:
1 |
|
Migration example
Previously we have relied on hard-coded roles, such as customer owner and project manager. Migration to dynamic roles on backend is relatively straightforward process. Consider the following example.
1 2 |
|
As you may see, we have relied on selectors with hard-coded roles. The main drawback of this approach is that it is very hard to inspect who can do what without reading all source code. And it is even hard to adjust this behaviour. Contrary to its name, by using dynamic roles we don't need to care much about roles though.
1 2 3 4 5 6 7 |
|
Here we use permission_factory
function which accepts permission string and list of paths to scopes, either customer, project or offering. It returns function which accepts request and raises an exception if user doesn't have specified permission in roles connected to current user and one of these scopes.
Permissions for viewing
Usually it is implemented filter backend, such as GenericRoleFilter
, which in turn uses get_connected_customers
and get_connected_projects
function because customer and project are two main permission aggregates.
1 2 3 4 5 6 |
|
Although this approach works fine for trivial use cases, often enough permission filtering logic is more involved and we implement get_queryset
method instead.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
Permissions for object creation and update
Usually it is done in serializer's validate method.
1 2 3 4 5 6 7 8 9 10 |
|
Quotas application
Overview
Quotas is Django application that provides generic implementation of quotas tracking functionality:
- Store and query resource limits and usages for project, customer or any other model.
- Aggregate quota usage in object hierarchies.
- Aggregate historical data for charting and analysis.
Define quota fields
Quotas are typically implemented on a per-model basis.
Model with quotas should inherit QuotaModelMixin
and define Quotas
class.
Quotas
class consists of set of quota fields. Consider the following example:
1 2 3 4 5 6 7 8 9 10 |
|
As you can see, Tenant model defines quota fields for number of virtual CPU cores, amount of RAM and storage.
Change object quotas usage and limit
To edit objects quotas use:
set_quota_limit
- replace old quota limit with new oneset_quota_usage
- replace old quota usage with new oneadd_quota_usage
- add value to quota usage
Do not edit quotas manually, because this will break quotas in objects ancestors.
Please note that aggregated usage is not stored in the database. Instead usage deltas are saved. The main reason behind it is to avoid deadlocks when multiple requests are trying to update the same quota for customer or project simultaneously.
Check if quota exceeded
To check if any of object quotas exceeded, use validate_quota_change
method of object with quotas.
This method receive dictionary of quotas usage deltas and returns errors if one or more quotas of object exceeded.
Sort objects by quotas with django_filters.FilterSet
Inherit your FilterSet
from QuotaFilterMixin
and follow next steps to enable ordering by quotas.
Add quotas__limit
and -quotas__limit
to filter meta order_by
attribute if you want to order by quotas limits. Ordering can be done only by one quota at a time.
Workflow for quota allocation
In order to prevent bugs when multiple simultaneous requests are performed, the following workflow is used.
1) As soon as we know what quota will be used we increase its usage.
It is performed in serializers' save or update method.
If quota usage becomes over limit, validation error is raised.
Consider for example InstanceFlavorChangeSerializer
in OpenStack plugin.
2) If backend API call for resource provision fails, frontend quota usage is not modified. Instead it is assumed that quota pulling is triggered either by user or by cron.
3) Quota usage is decreased only when backend API call for resource deletion succeeds.
Consider for example delete_volume
backend method in OpenStack plugin.
Declaring resource actions
Any methods on the resource viewset decorated with
@action(detail=True, methods=['post'])
will be recognized as resource
actions. For example:
1 2 3 4 5 6 7 8 9 |
|
Complex actions and serializers
If your action uses serializer to parse complex data, you should declare action-specific serializers on the resource viewset. For example:
1 2 3 4 |
|
Settings policy
Settings are used to configure behaviour of Waldur deployment. Settings can be used for configuration of both core and plugins, or dependent libraries.
Below is a policy for the settings.
Plugin settings
Plugins are defining their settings in the extension.py
. However, most probably not all settings might make sense to
override in production. Responsibility for highlighting what settings could be overridden in production are on
plugin developer.
Deployment settings
Deployment specific settings (e.g. for CentOS-8) are maintained as Python files and are kept in /etc/waldur/
:
override.conf.py
- all settings overwritten for the deployment apart from logging settings;features.json
- features setup for frontend;logging.conf.py
- logging configuration for Waldur
Tasks and executors
Scheduling Celery task from signal handler
Please use transaction.on_commit wrapper if you need to schedule Celery task from signal handler. Otherwise, Celery task is scheduled too early and executed even if object is not yet saved to the database. See also django docs
Executors
Waldur performs logical operations using executors that combine several tasks.
Executor represents a logical operation on a backend, like VM creation or resize. It executes one or more background tasks and takes care of resource state updates and exception handling.
Tasks
There are 3 types of task queues: regular (used by default), heavy and background.
Task registration
For class based tasks use old Task base class for compatibility:
1 |
|
For functions use decorator shared_task:
1 2 3 4 5 6 |
|
Regular tasks
Each regular task corresponds to a particular granular action - like state transition, object deletion or backend method execution. They are supposed to be combined and called in executors. It is not allowed to schedule tasks directly from views or serializer.
Heavy tasks
If task takes too long to complete, you should try to break it down into smaller regular tasks in order to avoid flooding general queue. Only if backend does not allow to do so, you should mark such tasks as heavy so that they use separate queue.
1 2 3 |
|
Throttle tasks
Some backends don't allow to execute several operations concurrently within the same scope. For example, one OpenStack settings does not support provisioning of more than 4 instances together. In this case task throttling should be used.
Background tasks
Tasks that are executed by celerybeat should be marked as "background". To mark task as background you need to inherit it from core.BackgroundTask:
1 2 3 4 |
|
Explore BackgroundTask to discover background tasks features.
Templates
The content of this document is autogenerated during CI job execution.
Waldur CI/CD
General Architecture
Waldur uses CI/CD approach for testing, packaging and deployment. The approach is implemented with GitLab CI system. It provides a framework for building pipelines. A pipeline consists of a sequence of stages, each of which depends on the result of a predecessor and includes smaller parts called jobs. A job is a sequence of actions executed for a specific purpose, e.g., testing an application.
The entire CI/CD pipeline consists of smaller pipelines, each of which resides in a corresponding repository and belongs to a particular part.
The CI pipelines are created for the following modules:
- Waldur Mastermind - REST API backend
- Waldur Homeport - frontend module
- Waldur Docker Compose - configuration for single-node deployment via Docker Compose
- Waldur Helm Chart - package with templates of Kubernetes manifests for workload resources
The CD pipelines were created for several Waldur deployments like Waldur development or production.
The following diagram illustrates the general picture of the pipeline.
Pipeline architecture for Waldur Components
Waldur components are the separate applications of Waldur. The two major ones are Waldur Mastermind and Waldur Homeport.
There are three main stages in the pipeline:
- Test, where the source code lint and unit testing takes place. This stage runs for each commit in a merge request and for the main branch commits;
- Build, where Docker image is being built. This stage runs for the main branch commits;
- Release, where Docker image from the last stage is being published in Docker Hub registry. This stage runs for the main branch commits.
Pipeline architecture for Waldur Deployment Templates
Waldur deployment templates are the configurations for different deployment environments. Currently, Waldur supports Docker Compose and Kubernetes. The structure of the latter one is based on Helm technology. The pipeline is shown below.
This pipeline includes two stages:
- Test, where the source code lint and configuration testing takes place. This stage runs for each commit in a merge request and the main branch commits;
- Release, where the configuration is published to GitHub. This step is implemented with GitLab mirroring.
Pipeline architecture for Waldur Deployments
In this context, deployments are repositories with values for further insertion into Waldur Deployment Templates. For example, they can be values for environmental variables used in Waldur containers. The pipeline is shown below.
There are three independent stages:
- Deploy, where Waldur release is installed or updated. This stage runs only for main branch commits. For Docker Compose environment, this stage is triggered automatically. For Kubernetes, it runs automatically only for update operations, while installation requires a manual trigger. Also, the update action runs by a schedule, e.g. at 5 AM;
- Test, where the running Waldur instance is tested. For example, it checks availability via HTTP requests sent to public Waldur endpoints;
- Undeploy, which removes the Waldur instance. This stage can be triggered only manually.
Development guidelines
Flow for feature tasks
- Create a new branch from develop
1 2 3 |
|
- Perform brilliant work (don't forget about tests!)
- Verify that tests are passing.
- Push all changes to origin (https://code.opennodecloud.com/)
- Create a Merge Request and assign it to a reviewer. Make sure that MR can be merged automatically. If not, resolve the conflicts by merging develop branch into yours:
1 2 |
|
- Resolve ticket in JIRA.
API ↵
API index
Summary:
Accounting
!! SWAGGER ERROR: Cannot use 2 different swagger files with same filename in same page. !!
Authentication
!! SWAGGER ERROR: Cannot use 2 different swagger files with same filename in same page. !!
Marketplace
!! SWAGGER ERROR: Cannot use 2 different swagger files with same filename in same page. !!
Organization
!! SWAGGER ERROR: Cannot use 2 different swagger files with same filename in same page. !!
Reporting
!! SWAGGER ERROR: Cannot use 2 different swagger files with same filename in same page. !!
User
!! SWAGGER ERROR: Cannot use 2 different swagger files with same filename in same page. !!
Ended: API
Plugins ↵
Plugins
Invoices plugin
Invoice price is calculated based on its items. For each object that should be added to invoice (invoice item source) should be created a separate model.
Business logic for invoice item creation and registration should be covered in a registrator in the module registrators.py
.
Invoice items creation and termination should be triggered in handlers that reacts on items sources deletion or save. RegistrationManager
should be used in handlers.
JIRA plugin
Configuration
-
Define active backend.
1 2 3 4 5 6 7 8
# For Service Desk WALDUR_SUPPORT.update({ 'ACTIVE_BACKEND': 'waldur_mastermind.support.backend.atlassian:ServiceDeskBackend', }) # For JIRA WALDUR_SUPPORT.update({ 'ACTIVE_BACKEND': 'waldur_mastermind.support.backend.atlassian:JiraBackend', })
-
Setup connection. Define server URL and user details to connect JIRA or Service Desk to Waldur:
1 2 3 4 5
WALDUR_SUPPORT['CREDENTIALS'].update({ 'server': <server URL>, 'username': <Atlassian user username>, 'password': <Atlassian user password>, })
-
Project setup. Define project key.
1 2 3
WALDUR_SUPPORT['PROJECT'].update({ 'key': <project key>, })
-
Project issues setup.
4.1. Make sure that selected project supports registered types of issues:
WALDUR_SUPPORT['ISSUE']['types']
.4.2. Make sure that project issues have fields that corresponds to
impact_field
,reporter_field
,caller_field
. It is possible to override default field names:
1 2 3 4 5WALDUR_SUPPORT['ISSUE'].update({ 'impact_field': <issue impact field name in JIRA or Service desk>, 'reporter_field': <issue reporter field name in JIRA or Service desk>, 'caller_field': <issue caller field name in JIRA or Service desk>, })
Web hook installation
It's possible to track updates of JIRA issues and apply them to Waldur immediately.
An instruction of JIRA configuration can be found at https://developer.atlassian.com/jiradev/jira-apis/webhooks
Step by step guide:
-
Log in to JIRA as administrator
-
Click on a cogwheel in the upper right corner and pick 'System'.
-
Scroll down to the lower left corner and find a "WebHook" option under the Advanced tab.
-
Now click on "Create a Web Hook" You will be presented with a web hook creation view. There are only 3 mandatory fields - Name, Status and URL.
4.1 Name your hook
4.2 Select whether you want to enable it. It can be disabled at any moment from to the same menu.
4.3 Configure a URL to send a POST request to. For instance: http://waldur.example.com/api/support-jira-webhook/ It is not needed to add any additional fields to request.
*Note: In case of VirtualBox localhost usually is 10.0.2.2. So the complete URL will be next:
http://10.0.2.2:8000/api/support-jira-webhook/*
4.4 Add a description.
4.5 Please make sure you've picked 'created, updated and deleted' actions under 'Events' section. No need to to check Comments events, they will be synced by the issue triggers.
4.6 Save configuration.
Waldur plugins
Plugin as extension
Waldur extensions are developed as auto-configurable plugins. One plugin can contain several extensions which is a pure Django application by its own. In order to be recognized and automatically connected to Waldur some additional configuration required.
Extensions' URLs will be registered automatically only if
settings.WALDUR_CORE['EXTENSIONS_AUTOREGISTER']
is True
, which is
default.
Create a class inherited from
waldur_core.core.WaldurExtension
. Implement methods which
reflect your app functionality. At least django_app()
should be implemented.
Add an entry point of name waldur_extensions
to pyproject.toml
:
1 2[tool.poetry.plugins.waldur_extensions] waldur_demo = "waldur_demo.extension:DemoExtension"
Plugin documentation
-
Keep plugin's documentation within plugin's code repository.
-
The documentation page should start with plugin's title and description.
-
Keep plugin's documentation page structure similar to the Waldur's main documentation page:
Guide - should contain at least installation steps. API - should include description of API extension, if any.
Valimo authentication plugin
Valimo endpoint allows to get Waldur authentication token using mobile PKI from Valimo. Please note, that only authentication is supported - no auto-registration is currently available.
-
To initiate a login process, please issue POST request against
/api/auth-valimo/
endpoint providing phone number as an input. -
On that request Waldur will create a result object (
AuthResult
) and request authentication from the Valimo PKI service. The result object contains all the metadata about the request, including fieldmessage
- text that is sent to the user via SMS. This text is typically shown to the user for validation purposes. -
The client is expected to poll for the authentication process by issuing POST requests against
/api/auth-valimo/result/
with UUID in the payload of a request. Please see details in the API documentation. -
After a successful login, endpoint
/api/auth-valimo/result/
will contain authentication token.
Openstack ↵
OpenStack plugin
OpenStack is a popular open-source toolkit for building private clouds.
OpenStack backups
Backups allow storing backups of instances outside of an OpenStack deployment and restoring it on other deployment.
On backup creation Waldur creates cinder backups for each volume of the instance, stores instance metadata and exports and saves metadata records of cinder backups.
On backup restoration Waldur creates cinder backups in a new tenant, based on saved metadata records. After that it creates new volumes and restores cinder backups into them. Finally, Waldur creates new instance based on restored volumes and backup metadata.
REST API
To create new backup, issue POST request with instance, backup name
and description to /api/openstack-backups/
endpoint. backup
has fields state
and runtime_state
that indicate backup creation
progress.
It is possible to update backup name and description with POST
request against /api/openstack-backups/<uuid>/
endpoint.
To restore backup - issue POST request with backup, new tenant and
new instance flavor against /api/openstack-backups/<uuid>/restore/
endpoint. Make sure that flavor is big enough for instance. You can
check backup metadata to get stored instance minimum ram, cores and
storage. On successful start of the restoration, endpoint will return
URL of an instance that should will be created from backup, field
state
of this instance indicates restoration process progress.
For more detailed endpoints description - please check endpoints documentation.
Resources import
Waldur is able to import existing OpenStack tenants, instances and volumes. This allows you take resources you've created and bring it under Waldur management.
To get list of available volumes to import send GET request to
marketplace-offerings/
To import volume send POST-request with the following parameters to
marketplace-offerings/
- project a UUID of project used for import;
- backend_id a backend id of the resource to be imported;
- plan an optional UUID of plan used for import.
OpenStack instances
When a VM instance is created through Waldur, it is created using Cinder service with 2 volumes:
- root volume containing OS root image, bootable;
- data volume an empty volume for data.
VM resize (flavor). To change memory or CPU number, a flavor should be changed. Please note, that the disk size is not affected. Change can happen only for a stopped VM.
VM resize (disk). Increasing a disk size means extension of the data volume attached to the instance. The process includes detaching of a data volume, extending it and re-attaching to a VM. Disk can be increased only for a stopped VM.
Ended: Openstack
Ended: Plugins
Ui ↵
Multilingual user interface
Workflow looks as following:
Markup TSX code using translate
function. For example:
translate('User details')
Always mark complete sentences for translation. If you combine fragments at runtime, there is no way for the translator to construct a proper sentence in their language. Do not combine strings together at runtime.
If you need to render JSX element inside of translated string, you should use formatJsxTemplate
function:
1 2 3 4 |
|
If translated string should be rendered inside of JSX element, you should use formatJsx
function:
1 2 3 4 5 |
|
Translation template is created automatically via Webpack. It will extract strings from TS and TSX files and put it in locales/template.pot
.
PO files are synced with Localazy service by GitLab CI pipelines.
All PO files are automatically converted by Webpack to JSON files.
Current user locale is stored in auth storage.
Role-based access control
Introduction
Waldur authorization system determines what user can do. It consists of permissions and roles. Permission is unique string designating action to be executed. Role is named set of permissions.
Permissions are defined in PermissionEnum
which is automatically generated from backend code and pushed to fronted code by GitLab CI. Most of the time you're going to use hasPermission
function which checks, whether user is allowed to perform action on given customer, project or offering. The following example shows how to check whether user is allowed to create offering in organization.
1 2 3 4 5 6 7 |
|
Migration examples
Previously we have relied on hard-coded roles, such as customer owner and project manager. Migration to dynamic roles on frontend is relatively straightforward process. Consider the following example.
1 2 3 4 5 6 7 8 9 |
|
As you may see, we have relied on selectors with hard-coded roles. The main drawback of this approach is that it is very hard to inspect who can do what without reading all source code. And it is even hard to adjust this behaviour. Contrary to its name, by using dynamic roles we don't need to care much about roles though.
1 2 3 4 5 6 7 8 9 10 |
|
The only prerequisite of course is to ensure that backend uses dynamic roles too.
Table component
- State management is done via
useTable
React hook. - Table rendering is done using
Table
component.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 |
|
Column definition consists of two mandatory fields: title
and render
.
In order to be able to make column optional, please specify hasOptionalColumns
property for table and ensure that key
property is defined for columns.
Terminology policy
We prefer British English over American English. For example, we use cancelled
instead of canceled
.
Should be applied for naming buttons, separate pages of the process and in list of actions.
Add / Remove
Should be used when an action of creating/adding or deleting/removing is applied to:
- Organizations
- Projects
- Providers
- VMs
- Applications
- SLA
- SSH key
- Team members
Import / Unlink
Should be used when an action of importing or unlinking / deleting a record without undeploying is applied to:
- VMs
Please use "synchronise" instead of "pull" in action title.
Testing
In order to run unit tests only once, execute command yarn jest
.
If you want to run server, which watches for changes in tests, run yarn jest --watch
.
Unit tests are used for testing React components, Redux actions, sagas, reducers, selectors.
Unit tests are written in the .spec.ts
files.
Integration tests are implemented using Cypress framework.
In order to run all integration tests, execute command yarn ci:test
.
If you already have Webpack server running, it's better to execute command yarn cypress open
.
Ended: Ui
Ended: Developer guide
User guide ↵
User Guide
This section contains instructions to typical operations done with Waldur. The section can be used as a basis for deployment-specific documentation.
Practical guides:
Marketplace and offering creation
Marketplace is a central module for provisioning of Waldur resources. Marketplace contains Offerings that belong to a special type of Organizations - Service Providers. Marketplace provides common functionality for resource lifecycle management, accounting and invoicing. Specifics are implemented in the Marketplace plugins (e.g. for OpenStack, SLURM, Rancher, etc).
Diagram of concepts
Adding a new Offering
To create a new Offering in the Marketplace, you need to:
- Assure that categories are configured in the Marketplace.
- Create at least one service provider.
- Create and activate a public offering.
Creating Marketplace categories
To create a category, either use administrative interface of Waldur, hosted under `/admin
(can be accessed by staff users)
or use management command for loading the pre-defined categories.
- With Docker-compose deployment:
1 |
|
- With Helm deployment
Open waldur-mastermind-worker shell and execute the following command:
- Get waldur-mastermind-worker pod name
1 2 3 |
|
- Connect to pod via shell
1 2 |
|
- Execute command to see available or add a category
1 |
|
Service provider registration
In Waldur, only organizations registered as service providers can create offerings and provide the service to users.
To register organization as service provider:
-
Open organization dashboard, click on "Edit" and select "Service provider" from the top menu.
-
Add service provider organization description. This description is visible in the Waldur marketplace under service provider list and under provider details.
-
Make sure that service provider organization category group is also set.
Offering creation
Waldur supports a number of different types of service providers when creating a shared offering. A common way of creating an offering is through a HomePort.
-
Select organization, which will provide the offering.
-
Go to Provider dashboard and click on "Marketplace" -> "Offerings" -> "Add new offering":
-
Click on "Add new offering" and fill in the name for the offering, category and type:
-
Offering details page opens, where you can add additional information:
-
Under Endpoints section, you can add access endpoints for the offering, for example, management consoles, SSH login nodes or similar.
This configuration will display then to resource of the offering a menu for easier navigation to the corresponding services. For SSH protocol this would trigger opening of an SSH client if configured for the browser. Out of the box works on OS X and Linux, requires configuration of the default application on Windows.
-
To add accounting components, select "Accounting components" from the top menu and then "Add component" from the right side. Accounting component is a measurable unit of a resource. For example, it can be CPU hours, GPU hours, storage hours, RAM etc.
-
A popup opens with possibility to configure fields and select the accounting type (whether the component is billed by the usage, max limit or it has a fixed price).
- Usage-based - billing is applied according to the actual usage of the resource during the billing period defined in the accounting plan after the submission of a usage report;
- Limit-based - billing is applied according to the requested/updated limits of a resource, actual usage can be below the limits and it is not the basis of the billing;
- Fixed price - billing is applied according to the exact values defined by the service provider in the accounting plan, limits and usage are not the basis for the accounting;
- One-time - billing is applied once on resource activation;
- One-time on plan switch - billing is applied once on resource activation and everytime a plan has changed, using pricing of a new plan.
-
To configure accounting frequency and prices, select "Accounting plans" from the top menu and then "Add plan" from the right. Select a name for the plan and accounting frequency:
-
To define prices for the components, select "Actions" and then "Edit prices". Set new price and save. If there is a need to provide higher priority access to resources with different prices, then it is advised to create another offering for this kind of cases.
-
If all set, click "Activate" on the top-right side to make it visible to everybody.
Tip
For more advanced cases of management of offerings, take a look at how a SLURM offering can be managed using Ansible module.
Cost and usage policies
Waldur allows to set different cost and usage policies on organization, project and offering level. For example, this means that organization owners and service providers can enable different actions, when cost or usage exceedes predefines level.
Cost policies for organizations
Staff role can define cost policies for organizations. To add a new policy, open Administrations menu from the left and then Organizations -> Cost policies from the top. This view provides an overview about already defined policies. To create a new one, select "Add" from the right.
From the popup, select organization, then set estimated cost limit and finally choose the action (what happens, when the limit is reached).
Cost policies for projects
Organization owners can set different cost policies for projects under particular organization. To add a new policy, open Organizations menu from the left and then Accounting -> Cost policies from the top. This view provides an overview about already defined policies. To create a new one, select "Add" from the right.
From the popup, select project, then set estimated cost limit and finally choose the action (what happens, when the limit is reached).
Cost policies for offerings
Offering managers can set cost policies for specific organization groups. This allows to trigger some actions, when cost is reached. To add new policy, offering manager should open offering management page (Organization from the left menu, then Service provider -> Marketplace -> Offering) and then Policy -> Cost policy from the top. This view provides an overview about already defined policies. To create a new one, select "Add" from the right.
From the popup, set estimated cost limit, choose the action what happens after cost is reached (block creation of new resources or notifying the organization owners). Then, it is needed to select period (is this policy per month, quarter, annual or total) and finally select organization group for which this policy applies to.
Usage policies for offerings
Offering manager can set different usage policies for specific organization groups. This allows to trigger some actions, when usage of defined resource component is reached. To add new policy, offering manager should open offering management page (Organization from the left menu, then Service provider -> Marketplace -> Offering) and then Policy -> Usage policy from the top. This view provides an overview about already defined policies. To create a new one, select "Add" from the right.
From the popup, select accounting component and set limit for that. Several compoments can be defined in one policy. Then, it is needed to select period (is this policy per month, quarter, annual or total) and finally select organization group for which this policy applies to.
Interface Introduction
Basics
Dashboard
- It is the first page you see (by default) after logging in to Waldur, which provides you with the initial necessary information of your profile, the Organizations and the Projects.
Organization / Project selection
- You can see the information about the organization only If you are at the organization level. It means if you are only at the project level, you can not go to the organization level.
Sidebar menu
- This is your main working tool in Waldur. Here you can manage your organizations, projects and resources. The next chapter of this guide will provide the details for each menu item.
Workspace menu (changes depending on sidebar menu)
- Each page in Waldur has a navigation bar at the top of the screen. It enables a quick access to organization/project info and management.
Workspace
- Shows organization, project or user dashboards related to the selection.
User related actions
- Contains all necessary action fields a user might need.
Issues
- Displays the list of user related issues. Here by Creating request you can request support.
Favorite Pages
- The opportunity to gather the most visited pages to make them easily reachable.
Pending confirmations
- Contains the list of requests related to user, resources or project management.
User Profile
- The main links related to the user actions like User Dashboard, Affiliations, Credentials, Notifications, Language and Color mode of the interface.
Get help
- By clicking Support you can find User Documentation, or reach us by using support email address and also create support request by going to "Issues" window.
Organization and project management
User guide for adding organizations
Note
Organization creation is only allowed for users in Staff role!
Organization in Waldur context means whatever grouping platform owner would like to have. This can mean for example research group, institution, department or working group. Organization has an owner who can manage the organization, projects and users connected to that project.
Create a new organization
- Login to Waldur and select "Organizations" from the left-side menu and then select "Add" from the right.
-
Fill the form and click "Create organization":
- Name - Name of the organization
- Contact email - email of the person, who is responsible for the organization
-
Organization edit page opens, where it is possible to add additional information, like policies, contact information. It is beneficial to assign a predefined category group (like private company, university, government, individial person etc) to organization.
Creation of projects
Project creation is allowed for organization owners in their organizations and staff users.
Prerequisites for creating projects:
1 |
|
- Select your home organization.
- Click on "Add project".
-
Fill the necessary fields (fields marked with * are mandatory).
- Project name - The original title of the project.
- Project description - A brief description about the project.
- OECD FoS code - OECD science field code (more info)
- End date - this is the end date for using the computational resources.
- Project image - Profile picture for the project (optional).
Project membership management
Project team contains users with different roles.
Please see this page for User Rights based on Roles in the Organization.
Adding project members
New user already has account in current Waldur instance
- Open your project in Waldur.
- Select "Team" from top menu and click on "Users".
-
By clicking "Add member" open "Add project member" window.
-
Select correct user, set the role and expiration date if necessary.
-
Finally, click on "Add".
- User now will get invitation email with the acceptance link.
New user don't have a account in current Waldur instance
- Open project in Waldur.
- Select "Team" from top menu and click on "Invitations".
- By clicking "Invite user" open "Invite by email" window.
- Insert user's email and set the role for the new user and continue.
- Fill in your custom message on the right side of the window and send the invitation.
- User now will get invitation email with the acceptance link.
Multiple projects removal via admin panel
An admin can remove projects with all related resources with the following sequence of actions:
- Go to admin panel (e.g.
http://localhost:8080/admin/
) - Open list of projects:
Structure tab
->Projects
- Filter the projects by organization field (optional)
- Select projects for removal
- Set action field to
Delete projects with all resources
Reporting
HomePort reports
Waldur HomePort includes a number of built-in reports based on the user activity. Reports can be accessed by staff and support users from the "Reporting" sidebar menu.
Grafana and Prometheus Metrics
Waldur supports exporters to Prometheus of different statistical metrics that can be used for building business dashboards, for example, in Grafana.
Check out details about the setup of the exporter.
Custom reports
It is possible to implement custom metric collection and report generation using Waldur SDK. Several examples are provided in the section for integrators.
Resource management
VPC management
Info
There are several Virtual Private Cloud providers available on the ´Marketplace´. You need to provision at least one VPC package from a suitable provider in order to be able to create virtual machines.
- Virtual Private Cloud (VPC) resource package can be added by clicking to ´Marketplace´ and selecting ´Private Clouds´ from the menu to go to the list of VPC.
- Currently, there are three VPC component names listed: ´Cores´, ´Ram´, and ´Storage´. For configuration of a VPC resource please fill in a suitable quantity for each component and click on the ´Add to cart´ button. Here by changing the quantities of components, you can see Prices accordingly per day, per 30 days, per 365 days, and finally the total price of the VPC.
- It is mandatory to input ´Tenant name´ to order a VPC.
- We also strongly suggest filling the ´Tenant description´ field.
- Finally click on Add to cart and Request on the next page.
Request approval
a) If your role in the Project is ´Project Manager´ or ´System Administrator´, please ask your Organization Owner to approve the order.
b) If your role is ´Organization Owner´ you are able to complete the purchase to final approval (click the ´Purchase´ button). Hereafter the system will need a couple of minutes to execute the order. Once the system changes the state to ´Done´, your VPC is ready to use.
Info
Provisioned VPC resource package will be automatically enabled for the project as a VM provider. For other projects it can be enabled by the organization owner under Provider management within organization workspace.
VM management
Info
Projects need to have at least one VPC resource package enabled before any virtual machines can be created. You can follow this guide to add a new VPC.
- VMs can be added by clicking to ’Marketplace’ and selecting ’Virtual machines’ from the menu to go to the list of Virtual Machines.
- Ordering a ’Virtual Machine’ requires a VM name and selection of a VM image.
- Please select the ’Image’ for a VM and click on the ’Select’ button, returning to the form.
- Selecting the initial VM resource profile, the flavor, by clicking on the ’Flavor: Show choices’ selector is mandatory.
- The flavor will set the initial resource profile for a VM - how much RAM, vCPU cores, and storage it will have.
Warning
VM images contain their minimum requirements information, and non-matching VM flavors are disabled automatically.
- Selecting VM flavor will also update ’System volume size’ with the option to override it manually (to a higher custom value). The size of ’Data Volume’ can be customized and incremented in 1 GB steps. ’System volume’ must be at least 10 GB, whereas ’System volume’ and ’Data volume’ must be equal to or less than VPC’s total Storage.
- By default, provisioned virtual machines expect users to log in using SSH keys. The initial SSH key for login should be selected by clicking on the ’SSH public key: Show choices’ selector.
Warning
There has to be at least one SSH public key added to the user profile for it to appear in the SSH key selector list.
Info
In order to log in to your newly created VM over SSH, you need to use a username depending on your choice of VM Image type and your SSH-RSA key-pair. By default password authentication is disabled.
- Default usernames for login are as follows:
- CentOS images: CentOS
- Ubuntu images: Ubuntu
- Debian images: Debian
- FreeBSD images: FreeBSD
- By default, no incoming connections will be allowed for a VM. Predefined Security Groups (firewall rules) must be linked to a VM in order to open up access (like ssh, HTTP, etc.). By clicking the ’Details’ button, you can see the details about the available ’Security Groups’. ’Security Groups’ can be added while ordering the VM or afterward by editing.
Info
VM create form will automatically include a ’default’ security group that enables egress (outgoing) traffic for a VM and which is required in order to reply to any of the incoming packets.
- VM needs to be connected to at least one of the VPC (internal) networks and an external network via floating IP - if external/public access to VM is required.
Info
Floating IP is technically realized as 1:1 NAT between VM internal IP and public network IP.
- We strongly suggest also adding ’VM description’. In order to provision the VM, please click on the “Add to cart” button.
Info
On the right pane, there will be a ’Checkout summary’ with the purchase overview and indicative VM cost (as part of the VPC package cost).
- VM should reach into “Active” status when successfully provisioned. The “Access” field will show the IP address to access VM over SSH (Linux) or over RDP (Windows).
Info
VM access over SSH or RDP should be permitted by ’Security Groups’ linked to VM.
HPC resource management
- HPC resources can be added by clicking to ´Marketplace´.
- Select organization and project (if not filled in yet) from the upper right corner.
- selecting ´HPC´ category or some other option which represent HPC resources.
- Select desired resource and click 'Deploy'.
- Fill in request form fields and click 'Create' on the right.
Resource components update
If it turns out that initial limits for the resource are too low or higher than expected, then it is possible to change the limits after the resource creation. This can be done by opening the resource management section. Again, like in the resource creation phase, same approval flow applies.
Accounting and usage reports
Accounting
Service provider revenue
If the organization is service provider, then it is possible to check the amount of revenue of a running month. To do that, open the organization dashboard, choose "Service provider" view and then dashboard opens. There you will see the total amount of estimated revenue and also 11 previous months.
By clicking on "Active clients" on the left, it's possible to see more detailed information about clients and amounts.
Invoices
Waldur provides a convenient way to see the invoices issued to the organization. Open the organization dashboard and select “Accounting” from the top menu and then “Invoices”. Now you’re able to see all invoices issued to the organization.
Invoices’ information can be downloaded in different formats as well.
Estimated cost
Estimated cost of a running month can be seen from the same view as invoices. By default, it shows top 4 projects with the highest cost. By clicking “Details”, you are able to see all projects with estimated costs.
Usage of a resources
To see overall usage information of resources, please select "Reporting" from the left-side menu and then "Usage reports" on the top menu.
It is possible to filter te results by organization, project, offering and export results.
To view the usage information within a project:
Private clouds
To view the usage information within a project:
-
Open your project in Waldur.
-
Select the private cloud resource that usage report you would like to see.
-
Now private cloud resource dashboard provides the overview of limits and used quotas.
HPC
-
Open your project in Waldur.
-
Select the allocation (resource) that usage report you would like to see.
-
On this window, Select "Usage" to see the usage of a resource. Use tabs "CPU Allocation", "GPU Allocation", and "Storage Allocation" to see the details.
-
By default, the view shows last 6 months information. To see the usage from the creation of a resource, please use period selector on the right side.
-
Instead of graph view, it is possible to switch to table view as well. To do that, please use switching button on the right next to the period selector.
-
It is possible to download the graph views as PNG images. To do that, please use the arrow icon on the right side of the graph.
To check the current resource allocation limit:
Ended: User guide
Integrations ↵
Integrations
Waldur supports integration with various private and public cloud services for delivering of additional functionality. The list of currently supported integrations is below. New services are integrated following business demand and can be delivered specifically for your deployment.
- OpenStack - OpenStack is a popular open-source platform for building private and public clouds. Waldur provides full integration with OpenStack clouds, in particular with Keystone, Nova, Cinder, Glance and Neutron services. Waldur can provision and manage OpenStack Projects, networks, subnets, floating IPs, instances and much more.
- MS Azure - Microsoft Azure is a well known public cloud provider. Waldur supports creation, import and management of Virtual Machines on Azure.
- SLURM - SLURM is a popular HPC workload manager and job scheduling system. Waldur supports integration with SLURM to enable web-based self-service for creating and managing accounts and allocations. More information
- Open OnDemand - Open OnDemand provides a remote web access to supercomputers. Waldur supports integration with Open OnDemand by integrating KeyCloak and SLURM plugins for seamless account and permission management. More information
- VMware - VMware provides virtualization, networking, and security management tools.
In addition to previously mentioned integration towards resource providers, Waldur also supports several identity providers like:
- EduGAIN - Support for federated academical identity provider EduGAIN. Waldur supports full integration as a EduGAIN Service Provider including CoCo extensions for higher security guarantees. More information
- LDAP - Support for taking identities from an external LDAP-server, e.g. FreeIPA, OpenLDAP or AD. Simple configuration for LDAP schema allows to connect your existing profiles with Waldur. More information
- MyAccessID - Support for integrating with GEANT's MyAccessID service. Full integration along with support for additional Puhuri-specific APIs. More information
- Keycloak - Support for integrating with Keycloak identity servers. Waldur is also able to maintain a list of groups in Keycloak that match Waldur's internal structure. More information
- SAML2 - Support for federated identity providers over SAML-based protocols. Automated account creation and update based on information from SAML-attributes.
- Waldur DB - Support for user profiles managed within local Waldur database. Does not require any additional configuration or setup. Fields of the profile can be tuned to match specifics of deployment (e.g. exposing additional names in national languages).
Glauth ↵
Systemd setup for glauth and config refresher
Prerequisites:
- Ensure
wget
is installed to a target machine as refreshing script uses it; - Install glauth binary to
/usr/bin/glauth
upon staring glauth service, e.g. glauth v2.3.0.
Refresher service
Copy the files from this repository to a corresponding paths on the target host:
1 2 3 4 5 |
|
Update .env
file for the refresher service, i.e. /etc/glauth/refresher.env
:
1 2 3 4 5 6 7 8 |
|
Update systemd daemon configs and start and enabled the service:
1 2 3 |
|
After some time, you should be able to check the prepared config file in /etc/glauth/config.cfg
Glauth service
Ensure glauth binary is installed in /usr/bin/glauth
and perform the same steps for the glauth service:
1 2 3 4 |
|
Ended: Glauth
Lexis ↵
Integrating LEXIS with Waldur
Creating a LEXIS link for a resource
To create a LEXIS link integration with a Waldur resource the API request shown below can be sent (http refers to HTTPie client).
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
Alternatively this can be done through UI of Waldur as shown below.
Note: To be able to create a LEXIS link for a resource using Waldur UI:
- the offering related to the resource has to have
plugin_options
set; - the feature
Enabled LEXIS link integrations for offerings.
should be enabled in Waldur site settings.
Namely:
- heappe_url
- heappe_username
- heappe_cluster_id
- heappe_local_base_path
You can set these settings via UI:
After offering setup, you can create a LEXIS link for an existing resource:
Listing all LEXIS links
To view all LEXIS links the API request shown below can be sent.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
|
Response example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
|
Note: A LEXIS link can be in one of the following states:
- Pending
- Executing
- OK
- Erred
Listing LEXIS links can alternatively be done through Waldur UI by visiting resource details
or use administration menu if you are a staff user
Listing resources supporting LEXIS links
To list all resources supporting LEXIS links, the following API request can be used:
1 |
|
The main filter is lexis_links_supported
parameter.
The example response:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 |
|
Deleting LEXIS links
To delete a LEXIS link the API request shown below can be sent.
1 2 3 4 5 6 7 8 9 10 11 12 13 |
|
Ended: Lexis
Open ondemand ↵
Integrating Open OnDemand with Waldur and SLURM
Components used
Open OnDemand is an open source software that empowers students, researchers, and industry professionals with remote web access to supercomputers.
Waldur is an open source platform for running HPC and Cloud self service.
SLURM is an open source, fault-tolerant, and highly scalable cluster management and job scheduling system for large and small Linux clusters.
Keycloak is an open source software product to allow single sign-on with identity and access management aimed at modern applications and services.
MyAccessID (optional) Identity and Access Management Service is provided by GEANT with the purpose of offering a common Identity Layer for Infrastructure Service Domains (ISDs).
Integration overview
OOD requirements
- Shared user directory storage available both on SLURM and OOD VMs
- Dedicated hostname for OOD machine (like ood.example.com)
- Open TCP/80 and TCP/443, ability to connect LDAP on SLURM management machine
- Linux server with at least 4GB of RAM and 10GB of storage disk
Open OnDemand (OOD) installation and configuration
Follow the guide at https://github.com/OSC/ood-ansible to automatically install OOD on the Linux server.
Preparation guide:
- Setup a certificate to later use in ansible configuration:
1 2 |
|
- In Keycloak create a client with authentication enabled for the Open OnDemand.
- Populate the ansible inventory.yaml:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 |
|
- Apply the playbook:
1 |
|
User authentication flow
-
OOD gets Linux username from preferred_username claim from Keycloak
-
OOD launches a "Per User Nginx" (PUN) environment after success user login
-
OOD connects to a SLURM cluster with the selected preferred_username
Keycloak configuration
Keycloak acts as a central Identity server for Waldur and Open OnDemand.
Steps to configure Keycloak:
- Configure Waldur and Open Ondemand clients
- Configure identity federation or user self-registration. If identity federation is used, common task is to configure username mapping like mentioned in https://puhuri.neic.no/idp_integration/use-cases/keycloak-integration/
- Install waldur-username-mapper for matching Keycloak or federated users with their respective Linux usernames: https://docs.waldur.com/integrations/waldur-keycloak-mapper/
Open OnDemand cluster configuration
To configure the connection between Open OnDemand and SLURM you need to manually configure the cluster config /etc/ood/config/clusters.d/my_cluster.yml:
1 2 3 4 5 6 7 8 9 |
|
waldur-slurm-agent configuration
Waldur-slurm-agent is a microservice for pulling allocation from Waldur and pushing the allocation usage statistics back to Waldur.
The microservice supports 2 modes of operation:
- docker-compose - testing only, requires SLURM running in the same docker compose
- native - production
Follow https://docs.waldur.com/integrations/waldur-slurm-service/ for installation guide. Make sure to enable the ENABLE_USER_HOMEDIR_ACCOUNT_CREATION flag - Open OnDemand does not work unless the user's home directory exists.
Host-based SSH authentication configuration
One of the methods to allow OOD to connect to SLURM login node is to setup a host-based “trust” or “SSH host-based authentication” between OOD VM and SLURM login node.
Use https://en.wikibooks.org/wiki/OpenSSH/Cookbook/Host-based_Authentication as a guide.
Troubleshooting
- OOD login and preferredUsername fetching errors are located in /var/log/httpd/error.log or similar
- Per user application or SLURM configuration errors are located in /var/log/ondemand-nginx/USERNAME/
- By default, OOD does not well tolerate setting arbitrary prepends for the URL — prefer using https://ood.example.com instead of https://ood.example.com/
- Most common SSSD / LDAP configuration errors include:
- Wrong LDAP filter
- SSSD is not able to reach LDAP server (network error)
- SSSD installed without sssd-ldap plugin
- Home directory of the user has not been created
- Make sure to specify correct SLURM account in the OOD job configuration:
Ended: Open ondemand
Service desk ↵
Service Desk integrations
Waldur supports integrations with several widely used service desk solutions. Integration allows creation of support requests directly from Waldur. In addition, replies from the support personnel are synchronised with Waldur so that the end users are never directly exposed to the service desk software. Users can see the issues' history, current status of active tickets as well as are able to interact with tickets from within Waldur.
Currently supported service desk solutions:
- Atlassian ServiceDesk (on-prem and cloud);
- Zammad;
- Microfocus SMAX.
Ended: Service desk
Waldur keycloak mapper ↵
Waldur Keycloak mapper
Waldur OfferingUser username mapper
Custom Keycloak client mapper for Waldur OfferingUser usernames.
Waldur Offering access mapper
Custom Keycloak client mapper for Waldur groups.
Waldur MinIO mapper
Custom Keycloak client mapper for MinIO.
This mapper adds policy
claim to a JSON token with a list of user permissions on a specified scope in Waldur.
For now, only customer
and project
are supported as a scope types for user permissions.
For example, if a user is an owner in customers C1, C2 and a manager in projects P1 and P2, the result would be:
- For scope
customer
:policy=<C1_UUID>,<C2_UUID>
- For scope
project
:policy=<P1_UUID>,<P2_UUID>
Installation and setup
Custom mapper setup includes the following steps:
-
Download the jar file to your machine, e.g. one of these releases.
-
Add the jar file to the providers directory. If a Keycloak server is running in a Docker container via Docker Compose, you can mount the file as a volume:
1 2 3 4 5 6 7 8
keycloak: image: "quay.io/keycloak/keycloak:18.0.2" container_name: keycloak command: start-dev --http-relative-path /auth ports: - "${KEYCLOAK_PORT:-8080}:8080" volumes: - waldur-keycloak-mapper-1.0.jar:/opt/keycloak/providers/waldur-keycloak-mapper-1.0.jar
-
Restart the deployment to apply the changes.
-
You can find the mapper in client menu under "Mappers" section. The title is "Waldur preferred username mapper"
Ended: Waldur keycloak mapper
Waldur keycloak minio mapper ↵
waldur-keycloak-minio-mapper
Custom Keycloak client mapper for MinIO.
This mapper adds policy
claim to a JSON token with a list of user permissions on a specified scope in Waldur.
For now, only customer
and project
are supported as a scope types for user permissions.
For example, if a user is an owner in customers C1, C2 and a manager in projects P1 and P2, the result would be:
- For scope
customer
:policy=<C1_UUID>,<C2_UUID>
- For scope
project
:policy=<P1_UUID>,<P2_UUID>
Installation and setup
Custom mapper setup includes the following steps:
-
Download the jar file to your machine, e.g. one of these releases.
-
Add the jar file to the providers directory. If a Keycloak server is running in a Docker container via Docker Compose, you can mount the file as a volume:
1 2 3 4 5 6 7 8
keycloak: image: "quay.io/keycloak/keycloak:18.0.2" container_name: keycloak command: start-dev --http-relative-path /auth ports: - "${KEYCLOAK_PORT:-8080}:8080" volumes: - waldur-keycloak-minio-mapper-1.0.jar:/opt/keycloak/providers/waldur-keycloak-minio-mapper-1.0.jar
-
Restart the container to apply the changes.
-
You can find the mapper in client menu under "Mappers" section named "Waldur MinIO mapper"
Ended: Waldur keycloak minio mapper
Ended: Integrations
Integrator guide ↵
Ansible module for Waldur
Waldur-based solutions can be managed with Ansible modules to allow provisioning and management of infrastructure under Waldur through Ansible playbooks.
Supported functionality
- OpenStack management.
- SLURM HPC management
- Common client for Waldur APIs in Python.
See also: http://docs.ansible.com/ansible/modules.html
Installation
1 |
|
Example usage
Configure an Ansible playbook with parameters
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
Pass parameters to an Ansible playbook
1 2 3 4 |
|
Running playbook using virtual Python environment
If you've installed Ansible Waldur module to virtual Python environment you need to specify path to Python interpreter and path to module library along with path to playbook:
1 2 3 4 |
|
Contributing
- See general guidelines: https://docs.ansible.com/ansible/latest/dev_guide/developing_modules_general.html
- Install
pre-commit
andtox
1 2 |
|
- When new module is implemented, don't forget to update
py_modules
section insetup.py
file. - When new module is implemented, it should be covered with tests. Run tests using
tox
1 |
|
- Module name should consist of three parts separated by underscore:
waldur
, plugin name, entity name. For example,waldur_os_snapshot
refers to OpenStack (OS) as plugin name and snapshot as entity name.
Reporting
Examples below show how it's possible to use Waldur SDK for generation of custom reports.
Running the scripts
All of the scripts below should be saved as files and executed in the environment with installed Waldur SDK. Please make sure that you have python3 and pip installed in your command line.
Make sure that you update WALDUR_HOST
and TOKEN
with values that match your target Waldur deployment.
1 2 |
|
Project reporting
The first scenario is report generation about monthly costs of each project.
The name of the output file is project-report.csv
.
Code example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 |
|
Example of output file content:
1 2 3 4 5 |
|
OpenStack tenant reporting
The second scenario is report generation about quotas and monthly costs of OpenStack tenants.
The name of the output file is openstack-report.csv
.
Code example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 |
|
Example of output file content:
1 2 3 4 5 |
|
Reporting by provider
To get CSV summary of consumption by provider, the following script can be useful. Output will be a file per provider with a short summary of invoice items for the defined period.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 |
|
Waldur SDK
Waldur SDK is a python wrapper
for typical REST operations.
You can use it, if you want to send requests to Waldur REST API directly from Python.
SDK is represented by Python module called waldur_client.py
from ansible-waldur-module
repository.
Installation
Due to frequent SDK updates, installation from the public GitHub repository is highly recommended:
1 |
|
In order to perform operations, a user needs to create an instance of WaldurClient
class:
1 2 3 |
|
This instance provides interface for further interaction with Waldur and will be used across examples in related documentation.
Error handling
If the client fails to perform an operation, it raises WaldurClientException
. This can be handled using try...except
block.
Example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
|
Disabling TLS validation (not recommended!)
If you are running your commands against Waldur deployment with broken TLS certificates (e.g. in development), the trick below can be used to disable validation of certificates by SDK.
1 2 3 4 5 6 7 8 |
|
Air gapped installation
If your machine from where you run SDK is not connected to the public Internet, you can use the following method to transfer required libraries.
On the machine with access to the Internet:
1 2 3 |
|
Now transfer content of the dependencies folder and requirements.txt to a machine without public Internet and run.
1 |
|
APIs ↵
REST API
Authentication
Waldur uses token-based authentication for REST.
In order to authenticate your requests first obtain token from any of
the supported token backends. Then use the token in all the subsequent
requests putting it into Authorization
header:
1 2 3 4 |
|
Also token can be put as request GET parameter, with key x-auth-token
:
1 2 3 |
|
API version
In order to retrieve current version of the Waldur authenticated user should send a GET request to /api/version/.
Valid request example (token is user specific):
1 2 3 4 5 |
|
Valid response example:
1 2 3 4 5 6 7 8 |
|
Pagination
Every Waldur REST request supports pagination. Links to the next, previous, first and last pages are included in the Link header. X-Result-Count contains a count of all entries in the response set.
By default page size is set to 10. Page size can be modified by passing ?page_size=N query parameter. The maximum page size is 100.
Example of the header output for user listing:
1 2 3 4 5 6 7 8 9 10 |
|
Authentication
Outline:
Waldur MasterMind exposes REST API for all of its operations. Below are examples of typical operations performed against APIs. To run the examples, we are using a HTTPie.
Almost all of the operations with API require an authentication token. Below we list two methods on how to get it.
Authentication with username and password
If your account is allowed to use username/password and the method is enabled (e.g. in dev environment), you can get a new token by submitting a username/password as JSON to a specific endpoint.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 |
|
Authentication Token management
The easiest way to get your token is via Waldur HomePort. Go to user workspace by selecting 'Manage' in the user drop-down.
Scroll down to the Current API token field and click on the 'eye' icon to display the token.
Permissions
Listing permissions
Entities of Waldur are grouped into organisational units. The following organisational units are supported: customer and project.
Each organisational unit has a list of users associated with it. Getting a list of users connected to a certain organisational unit is done through running a GET request against a corresponding endpoint.
- customer: endpoint
/api/customer-permissions/
- project: endpoint
/api/project-permissions/
Filtering by organisational unit UUID or URL is supported. Depending on the type, filter field is one of:
?customer=<UUID>
?customer_url=<URL>
?project=<UUID>
?project_url=<URL>
?user_url=<URL>
In addition, filtering by field names is supported. In all cases filtering is based on case insensitive partial matching.
?username=<username>
?full_name=<full name>
?native_name=<native name>
Ordering can be done by setting an ordering field with
?o=<field_name>
. For descending ordering prefix field name with a
dash (-). Supported field names are:
?o=user__username
?o=user__full_name
?o=user__native_name
Fetch user data from Waldur using username
To fetch user data together with its permissions, you need to perform the following HTTP request.
It requires username
filter and valid API token.
1 2 3 4 |
|
Example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 |
|
Ended: APIs
Existing integrations ↵
VPNaaS custom script - Provisioning VPN as a Service based on Firezone
This python script provisions VPN as a Service based on Firezone in OpenStack in Waldur. It uses Flatcar Linux and a butane binary that the user needs to provide inside a Docker container used for running Waldur custom scripts.
An additional requirement is an OpenID Connect provider for end-user authentication in Firezone. Default VPN port: UDP/51820.
System requirements
- Keycloak with admin access for OpenID Connect client creation
- Butane for converting Flarcar Linux yaml config into json
- OpenStack nova for running the Firezone VM
- OpenStack designate for the VM FQDN generation. Firezone will use that FQDN for HTTPS certificate generation.
Firezone VM needs Internet connection for Let's Encrypt certificate generation and Github access for script download.
Setup guide
- Prepare waldur custom script runner container to have Butane and required Python packages
- Paste the create.py into the creation script and terminate.py into the termination script
- Populate environment variables
- Add user input field with internal name "tenant" and type - "Select OpenStack tenant", make it a required field
Environment Variables
The following environment variables need to be provided in the Waldur custom script:
WALDUR_API_URL
- API URL of Waldur that holds OpenStackWALDUR_API_TOKEN
- Waldur API tokenKEYCLOAK_URL
- Keycloak address for creating OpenID connect clientsKEYCLOAK_USERNAME
- Keycloak admin usernameKEYCLOAK_PASSWORD
- Keycloak admin passwordKEYCLOAK_REALM
- Keycloak realmCREATOR_EMAIL
- Email of the user, that created the VPN instanceIMAGE
- OpenStack imageFLAVOR
- OpenStack flavorSYSTEM_VOLUME_SIZE
- Size of the system volume for OpenStack VMRUN_BUTANE_IN_DOCKER
- When set to True - run butane in docker container instead of just binary
Waldur Guacamole integration
Guacamole is a browser based remote desktop gateway. It supports standard protocols like VNC, RDP, and SSH. Waldur — Guacamole integration is based on Waldur's custom scripts functionality.
This integration provides full virtual desktop lifecycle, including:
- Creation of a virtual desktop in remote Waldur (i.e. OpenStack KVM machine)
- Adding records of a freshly created virtual desktop to Guacamole MySQL database
- Termination of the virtual desktop and MySQL records removal upon desktop deletion
Quick Start Guide
- Make sure your Waldur is able to run custom scripts
- Modify Guacamole MySQL database to store backend ID (Backend Waldur resource ID):
1 |
|
- Create a Service Offerring in Waldur with "Custom Script" type
- Configure environment variables for the service:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
|
- Copy
custom-scripts/create.py
andcustom-scripts/terminate.py
as the creation and termination scripts for the service