{"id":15674452,"url":"https://github.com/ipspace/vlan-service","last_synced_at":"2025-05-06T22:58:11.495Z","repository":{"id":148026004,"uuid":"80305926","full_name":"ipspace/VLAN-service","owner":"ipspace","description":"Set of playbooks used to deploy a VLAN-based service.","archived":false,"fork":false,"pushed_at":"2017-02-28T09:40:15.000Z","size":51,"stargazers_count":14,"open_issues_count":0,"forks_count":8,"subscribers_count":3,"default_branch":"VLAN","last_synced_at":"2025-05-06T22:58:00.457Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ipspace.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-01-28T19:35:33.000Z","updated_at":"2022-10-13T20:13:24.000Z","dependencies_parsed_at":"2023-04-29T15:01:20.207Z","dependency_job_id":null,"html_url":"https://github.com/ipspace/VLAN-service","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipspace%2FVLAN-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipspace%2FVLAN-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipspace%2FVLAN-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipspace%2FVLAN-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ipspace","download_url":"https://codeload.github.com/ipspace/VLAN-service/tar.gz/refs/heads/VLAN","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252782482,"owners_count":21803383,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-03T15:44:59.742Z","updated_at":"2025-05-06T22:58:11.471Z","avatar_url":"https://github.com/ipspace.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Manage a simple VLAN service\n\nThe **vlan.yml** playbook in this repository manages (add/modify/remove) a simple VLAN service described in the *services.yml* data model on NX-OS switches.\n\n## Explore the progress\n\nI created a number of git branches while developing this example to allow you to explore various stages of the project. Use \u003ccode\u003egit checkout *branch*\u003c/code\u003e to check out the desired stage of the project into your working directory.\n\nThe branches you can explore are:\n\n* ***VLAN_Initial*** - initial implementation that provisions VLAN database, interfaces and access VLANs straight from the services data model\n* ***VLAN_Data_Model*** - transforms services data model into per-node data model at the beginning of the playbook for easier processing. The introduction of per-node data model simplified the provisioning process.\n* ***VLAN_Decommission*** - add support for service decommissioning and customer site description in the services data model, which triggered changes in data model transformation and minor adjustments in service provisioning process.\n* ***VLAN_Validation*** - validates successful deployment of VLAN services: VLANs are created and configured as access VLANs on service ports.\n* ***VLAN_Cleanup*** - cleanup of VLANs and service ports no longer used by active services.\n* ***VLAN_PreDeploy_Check*** - check the actual hardware before service deployment\n* ***Logging*** - extensive logging and debugging support\n* ***Plugins*** - Jinja2 filter plugins are used for unique key and composite key tests\n* ***Transactions*** - integration with an external transaction system\n* ***MultiVendor*** - add multi-platform/vendor support\n\n## Data model\n\nService definition file (services.yml) is a YAML dictionary with every customer being a key/value pair. Each customer record has a **vlan** key (VLAN# used for this customer) and a list of active service ports (**ports** key). Later stages of the project add **state** key to indicate a service should be removed (when **state** is set to **absent**).\n\nThe list of service ports is a list of dictionaries, each one of them having:\n* **node**: device on which the service port is configured\n* **port**: port on the device\n* **site**: site name within customer network (used for interface descriptions)\n\nHere's a sample service definition file:\n\n    ---\n    ACME:\n      vlan: 100\n      ports:\n      - { node: leaf-1, port: \"Ethernet2/1\", site: \"ACME Downtown\" }\n      - { node: leaf-2, port: \"GigabitEthernet0/1\", site: \"ACME Remote\" }\n\n    Wonka:\n      vlan: 200\n      state: absent\n      ports:\n      - { node: leaf-1, port: \"Ethernet2/3\"}\n      - { node: leaf-2, port: \"GigabitEthernet0/3\" }\n\n## Transaction data model\n\nTransaction file (samples in ***tests/transactions*** directory) is a YAML dictionary describing a single customer. \n\nEvery transaction must have:\n* **cid** - customer ID (number)\n* **vlan** - VLAN# used for the customer (number)\n* **name** - name of the customer (no spaces allowed)\n* **ports** - list of ports used by the customer.\n* **state** (optional) - value `absent` indicates customer removal request).\n\nThe list of service ports is a list of dictionaries, each one of them having:\n* **node**: device on which the service port is configured\n* **port**: port on the device\n* **site**: site name within customer network (used for interface descriptions)\n* **state**: optional - value `absent` indicates port removal request\n\nHere's a sample transaction file:\n\n    cid: 42\n    vlan: 100\n    name: ACME\n    ports:\n      - { node: leaf-1, port: \"Ethernet2/1\", state: absent }\n      - { node: leaf-2, port: \"Ethernet2/3\", site: \"Remote\" }\n\n## Tests\n\nAll the tests included in this project are in *tests* directory:\n\n* ***model.yml*** - creates per-node data models and stores them in *printouts* directory\n* ***cleanup-test.yml*** - test harness for the cleanup module\n* ***predeploy.yml*** - test harness for pre-deploy checks\n* ***list-plugin.yml*** - unit tests for `append` plugin in ***list.py***\n* ***unique-plugin.yml*** - unit tests for `dupattr` plugin in ***list.py***\n* ***trans-model.yml*** - transforms a single transaction into a set of per-node data models\n\nThe same directory contains bash scripts that execute a suite of unit tests:\n\n* ***run-predeploy-tests*** executes ***predeploy.yml*** playbook for every `*pdf*` test in the ***services*** subdirectory\n* ***run-transaction-model-tests*** executes ***trans-model.yml*** for every transaction in the ***transactions*** directory\n\nThe tests use multiple scenarios stored in various subdirectory of the tests directory:\n\n* ***input*** - data generated by various ***show*** commands (used for cleanup tests). Scenarios are generated by executing **show** commands on NX-OS with the **create-getinfo-scenario.sh** scripts.\n* ***services*** - unit test scenarios for pre-deploy checks; include numerous valid service scenarios as well as scenarios that are supposed to fail (`*pdf*`) or succeed (`*pdok*`).\n* ***transactions*** - sample transactions and valid per-node data models generated from those transactions\n\nFurther bash scripts create additional testing files:\n\n* ***create-model-scenario.sh*** creates a set of JSON per-node data models from a services data model.\n* ***generate-transaction-tests.sh*** creates valid JSON per-node data models from sample transactions (run only when you're absolutely sure the transformation template works correctly)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fipspace%2Fvlan-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fipspace%2Fvlan-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fipspace%2Fvlan-service/lists"}