{"id":22529451,"url":"https://github.com/test-kitchen/vmware-vra-gem","last_synced_at":"2025-08-27T02:19:27.112Z","repository":{"id":35101588,"uuid":"39275246","full_name":"test-kitchen/vmware-vra-gem","owner":"test-kitchen","description":"A Ruby Gem for interacting with the VMware vRealize Automation system","archived":false,"fork":false,"pushed_at":"2024-06-26T21:12:50.000Z","size":292,"stargazers_count":16,"open_issues_count":7,"forks_count":31,"subscribers_count":26,"default_branch":"main","last_synced_at":"2025-08-18T06:46:44.984Z","etag":null,"topics":["hacktoberfest","managed-by-terraform","ruby","ruby-gem","test-kitchen","testing","vmware-vra-gem","vmware-vrealize-automation","vra"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"golang/go","license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/test-kitchen.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","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,"zenodo":null}},"created_at":"2015-07-17T21:06:47.000Z","updated_at":"2025-04-09T10:10:30.000Z","dependencies_parsed_at":"2023-01-15T13:52:33.444Z","dependency_job_id":"ad32f01c-119a-4624-a8fb-f506a9ede581","html_url":"https://github.com/test-kitchen/vmware-vra-gem","commit_stats":{"total_commits":181,"total_committers":23,"mean_commits":7.869565217391305,"dds":0.7624309392265194,"last_synced_commit":"05d457d9419f6f122a39b1347e645bf93f2a4719"},"previous_names":["chef-partners/vmware-vra-gem"],"tags_count":41,"template":false,"template_full_name":null,"purl":"pkg:github/test-kitchen/vmware-vra-gem","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/test-kitchen%2Fvmware-vra-gem","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/test-kitchen%2Fvmware-vra-gem/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/test-kitchen%2Fvmware-vra-gem/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/test-kitchen%2Fvmware-vra-gem/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/test-kitchen","download_url":"https://codeload.github.com/test-kitchen/vmware-vra-gem/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/test-kitchen%2Fvmware-vra-gem/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272280357,"owners_count":24906116,"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","status":"online","status_checked_at":"2025-08-27T02:00:09.397Z","response_time":76,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["hacktoberfest","managed-by-terraform","ruby","ruby-gem","test-kitchen","testing","vmware-vra-gem","vmware-vrealize-automation","vra"],"created_at":"2024-12-07T07:14:46.028Z","updated_at":"2025-08-27T02:19:27.096Z","avatar_url":"https://github.com/test-kitchen.png","language":"Ruby","readme":"# VMware vRA Gem\n\n[![Gem Version](https://badge.fury.io/rb/vmware-vra.svg)](http://badge.fury.io/rb/vmware-vra)\n\nClient gem for interacting with VMware's vRealize Automation application.\n\nNot all vRA functionality is included in this gem; only API calls necessary\nto interact with the catalog, requests, and existing items is included.\n\nThe primary goal of this gem is to provide a reusable set of methods in order\nto create Chef plugins for knife, test-kitchen, and provisioning.\n\n## Versions\n\n`1.7.0` version can and will support vRA 6 and below.\n\n`2.0.0` version and forward will support vRA 7+.\n\n`3.0.0` version and forward will support vRA 8+.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'vmware-vra'\n```\n\nAnd then execute:\n\n```shell\nbundle\n```\n\nOr install it yourself as:\n\n```shell\ngem install vmware-vra\n```\n\n## Usage\n\nFirst, load in the gem.\n\n```shell\nrequire 'vra'\n=\u003e true\n```\n\nThen, set up your client object. You will need to know your domain from your vRA administrator.\n\n```shell\nclient = Vra::Client.new(username: 'devmgr@corp.local', password: 'mypassword', domain: 'domain.corp.local', base_url: 'https://vra.corp.local', verify_ssl: true)\n=\u003e #\u003cVra::Client:0x000000034c0df8 ... \u003e\n```\n\n### Catalog Types\n\nTo list all the catalog types:\n\n```shell\nclient.catalog.all_types\n =\u003e [#\u003cVra::CatalogType:0x00007fcde6855370 @id=\"com.vmw.vro.workflow\", @data={\"id\"=\u003e\"com.vmw.vro.workflow\", ... ]\n```\n\n### Catalog Sources\n\nTo list all the catalog sources:\n\n```shell\nclient.catalog.all_sources\n[#\u003cVra::CatalogSource:0x00007fcde3948c30 @id=\"2f5b2d5c-6dc2-4ea7-b304-cd8fea5ede0f\", @data= ...]\n```\n\nAnd to list the sources that are entitled only:\n\n```shell\nclient.catalog.entitled_sources(project_id)\n=\u003e [#\u003cVra::CatalogSource:0x00007fcde2a28c00 @id=\"18102dc2-9e48-487a-93a8-aafab2ecc05 ...]\n```\n\nCreating a new source can be done as follows:\n\n```shell\nsource = Vra::CatalogSource.create(client, name: 'New source', catalog_type_id: 'com.vmw.vro.workflow', project_id: project_id)\n =\u003e #\u003cVra::CatalogSource:0x00007fad651f63b8 ... \u003e\n```\n\n### Catalog Items\n\nTo list all items in the catalog:\n\n```shell\nclient.catalog.all_items\n =\u003e [#\u003cVra::CatalogItem:0x00007fe583863b28\u003e, #\u003cVra::CatalogItem:0x00007fe583863ad8 ... ]\n```\n\nTo only list the items in the catalog for which you are entitled to request:\n\n```shell\nclient.catalog.entitled_items(project_id)\n=\u003e [#\u003cVra::CatalogItem:0x00007fe583863b28\u003e, #\u003cVra::CatalogItem:0x00007fe583863ad8 ... ]\n```\n\nTo retrive catalog id from catalog name:\n\n```shell\nclient.catalog.fetch_catalog_items('centos')\n =\u003e\n[#\u003cVra::CatalogItem:0x00007fb734110f60\n  @id=\"f2e8c6ee-dd00-32c4-94c7-0a50046cb2f3\",\n  @data={\n    \"name\"=\u003e\"oe-centos-1633598756_bp\",\n  ...\u003e\n]\n```\n\n### Requesting Deployments\n\nWhen you are ready to request a deployment using a catalog, create a new deployment object:\n\n```shell\nrequest = client.catalog.request(\n  catalog_id, \n  image_mapping: 'VRA-nc-lnx-ce8.4-Docker',\n  flavor_mapping: 'Small',\n  name: 'CentOS VRA8 Test',\n  project_id: project_id,\n  version: '1'\n)\n =\u003e\n#\u003cVra::DeploymentRequest:0x00007fb7340b7438\n...\n```\n\nTo request a deployment from a catalog item, you can use the above method with a project ID that has a cloud template version released to the project.\n\nThe ID of the catalog item from which you are requesting the deployment should be also included, and the version of the released cloud template. If the user doesn't specify a version explicitly, the latest version will be fetched automatically and will be used for the request.\n\nAdditionally, the name of the deployment should be specified and it should be unique.\nThe image mapping specifies the OS image for a VM and the flavor mapping specifies the CPU count and RAM of a VM.\n\nIf your catalog blueprint item requires additional parameters to successfully submit your request, you may add them:\n\n```shell\nrequest.set_parameter('my_parameter', 'string', 'my value')\n```\n\n### Managing the deployment\n\nNow, submit your request!  The client will return a new \"Deployment\" object you can use to query for status.\n\n```shell\ndeployment = catalog_request.submit\n=\u003e #\u003cVra::Deployment:0x000000027caea0 ... \u003e\n\ndeployment.status\n=\u003e \"IN_PROGRESS\"\n```\n\nYou can refresh your deployment object to get the latest status:\n\n```shell\ndeployment.refresh \u0026\u0026 deployment.status\n=\u003e \"SUCCESSFUL\"\n```\n\nYou can also save the deployment ID for later, and create a new deployment object at your leisure to follow-up on your deployment request:\n\n```shell\ndeployment.id\n=\u003e \"aed22465-02db-481d-b55a-cefe216096a2\"\n\nnew_deployment = client.deployments.by_id('aed22465-02db-481d-b55a-cefe216096a2')\n=\u003e #\u003cVra::Deployment:0x0000000564ac30 ... \u003e\n\nnew_deployment.status\n=\u003e \"CREATE_SUCCESSFUL\"\n```\n\n### Deployment Resources\n\nWhen the deployment request is successful, you can query the resources created as the result of your request. Assuming that the catalog item blueprint we requested only creates a single VM, we can get that resource and learn more information about it:\n\n```shell\nresource = deployment.resources.first\n=\u003e #\u003cVra::Resource:0x00000006772e68 ... \u003e\n\nresource.network_interfaces\n=\u003e [{\"NETWORK_ADDRESS\"=\u003e\"192.168.110.203\", \"NETWORK_MAC_ADDRESS\"=\u003e\"00:50:56:ae:1d:c7\", \"NETWORK_NAME\"=\u003e\"vxw-dvs-35-virtualwire-2-sid-5000-Edge_Transport\"}]\n\nresource.ip_addresses\n=\u003e [\"192.168.110.203\"]\n\nresource.name\n=\u003e \"hol-dev-32\"\n```\n\nIf you have the resource_id and the deployment object, you can fetch the resources details as follows\n\n```shell\nresource.id\n=\u003e \"331fd10b-f2a2-40ae-86bc-1255c1ee9a6d\"\n\nnew_resource = deployment.resource_by_id('331fd10b-f2a2-40ae-86bc-1255c1ee9a6d')\n=\u003e #\u003cVra::Resource:0x000000067c13b0 ... \u003e\n\nnew_resource.name\n=\u003e \"hol-dev-32\"\n```\n\n### Deleting a deployment from vRA\n\nWhen you no longer need the VM, you can destroy the deployment which will delete all the associated resources as well.\nThe method will return a request object you can query for status:\n\n```shell\ndestroy_req = deployment.destroy\n=\u003e #\u003cVra::Request:0x00000006ea90d8 ... \u003e\n\ndestroy_req.status\n=\u003e \"SUCCESSFUL\"\n```\n\nYou can also list all resources and requests you have permission to see with these methods:\n\n```shell\ndeployment.resources\ndeployment.requests\n```\n\n### Pagination\n\nvRA paginates API requests where lists of items are returned.  By default, this gem will ask vRA to provide items in groups of 20.  However, as reported in [Issue 10](https://github.com/chef-partners/vmware-vra-gem/issues/10), it appears vRA may have a pagination bug.  You can change the default page size from 20 to a value of your choice by passing in a `page_size` option when setting up the client:\n\n```ruby\nvra = Vra::Client.new(username: 'devmgr@corp.local', password: 'mypassword', domain: 'domain.corp.local', base_url: 'https://vra.corp.local', verify_ssl: true, page_size: 100)\n```\n\n... or setting `page_size` on the client object after you've created it:\n\n```ruby\nclient.page_size = 100\n```\n\n### Debugging\n\nTo aid diagnosis of deep API issues, set the following environment variable to enable logging of all API requests. Note that this will include requests to retrieve the bearer token.\n\nMacOS/Linux:\n\n```ruby\nexport VRA_HTTP_TRACE=1\n```\n\nWindows:\n\n```powershell\n$env:VRA_HTTP_TRACE=1\n```\n\n## License and Authors\n\nAuthor:: Chef Partner Engineering (\u003cpartnereng@chef.io\u003e)\n\nCopyright:: Copyright (c) 2022 Chef Software, Inc.\n\nLicense:: Apache License, Version 2.0\n\nLicensed under the Apache License, Version 2.0 (the \"License\"); you may not use\nthis file except in compliance with the License. You may obtain a copy of the License at\n\n```text\nhttp://www.apache.org/licenses/LICENSE-2.0\n```\n\nUnless required by applicable law or agreed to in writing, software distributed under the\nLicense is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,\neither express or implied. See the License for the specific language governing permissions\nand limitations under the License.\n\n## Contributing\n\n1. Fork it ( \u003chttps://github.com/[my-github-username]/vmware-vra-gem/fork\u003e )\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create a new Pull Request\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftest-kitchen%2Fvmware-vra-gem","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftest-kitchen%2Fvmware-vra-gem","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftest-kitchen%2Fvmware-vra-gem/lists"}