vmware-vra 2.7.0 → 3.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: adc7871ce36fca6a61e634ea47bd4453e12d0c57fd2a53b30d67b327f819a7e5
-  data.tar.gz: 8f9ad1fc148858c9f686c53f0818a3ad8af418eaa8dac845e2b36833b60274cf
+  metadata.gz: 95e805c8c8d6fd5228962ffa907ce07409b60022e29166ba970194e0aa61cc42
+  data.tar.gz: 49beb545bf435a61aefccf06daa25629ccd991363dc9ca7546e3a15996cca362
 SHA512:
-  metadata.gz: e007662f641db9438846aecb6bd5f2063cb55c961b1131b85433185cb86b8031b0e6978441c35bd7d55d67daf02667ee58ca8c025f58872569d5ed84c8ba9c91
-  data.tar.gz: 0343c931007f55fbbbe1fce15b516674a1ae46f74630d1d7a2b529d2c7068386e5b1a087447b58ac9ca68de06b1112a773acf406fe97de93a85af6cf57e62654
+  metadata.gz: de450415be0060fb3aef5d796e407bf9fedfb79b0f83a003d702073ee7aaa06508a5758191916d4c522c42348d166c01c23f8671221c2b8cd66b5e4b839177e7
+  data.tar.gz: ade68fa3e927d199c2c263bd1fcc918c21ea8c9aa52703ab74092461e9719c442294064c1410fc890c27d90908be089d21340141c11814db04cbccf3d1e4710a

data/.gitignore

@@ -15,4 +15,6 @@
 mkmf.log
 .direnv/
 .envrc
-.ruby-version
+.ruby-version
+.idea
+

data/CHANGELOG.md

@@ -1,4 +1,30 @@
 # Change Log
+## [3.0.1](https://github.com/chef-partners/vmware-vra-gem/tree/v3.0.1) (2022-01-25)
+[Full Changelog](https://github.com/chef-partners/vmware-vra-gem/compare/v3.0.0...v3.0.1)
+
+- Fix access token workflow to work with VRA8
+
+## [3.0.0](https://github.com/chef-partners/vmware-vra-gem/tree/v3.0.0) (2022-01-18)
+[Full Changelog](https://github.com/chef-partners/vmware-vra-gem/compare/v2.7.2...v3.0.0)
+
+- Rewritten to support vRA 8. If you require support for 7 make sure to pin on the previous 2.7.2 release.
+
+## [2.7.2](https://github.com/chef-partners/vmware-vra-gem/tree/v2.7.2) (2020-09-09)
+[Full Changelog](https://github.com/chef-partners/vmware-vra-gem/compare/v2.7.1...v2.7.2)
+
+- Added an extra option to handle shirt size parameter
+- Masking user credentials(password) in debug mode
+
+## [2.7.1](https://github.com/chef-partners/vmware-vra-gem/tree/v2.7.1) (2019-05-28)
+[Full Changelog](https://github.com/chef-partners/vmware-vra-gem/compare/v2.7.0...v2.7.1)
+
+**Closed issues:**
+
+- Some Extra Parameters are not passing through to VRA [\#75](https://github.com/chef-partners/vmware-vra-gem/issues/75)
+
+**Merged pull requests:**
+
+- Add support for boolean vRA parameters, fix deep merge, add tracing [\#76](https://github.com/chef-partners/vmware-vra-gem/pull/76) ([stuartpreston](https://github.com/stuartpreston))
 
 ## [2.7.0](https://github.com/chef-partners/vmware-vra-gem/tree/v2.7.0) (2019-05-10)
 [Full Changelog](https://github.com/chef-partners/vmware-vra-gem/compare/v2.6.1...v2.7.0)
@@ -287,4 +313,4 @@
 
 
 
-\* *This Change Log was automatically generated by [github_changelog_generator](https://github.com/skywinder/Github-Changelog-Generator)*
+\* *This Change Log was automatically generated by [github_changelog_generator](https://github.com/skywinder/Github-Changelog-Generator)*

data/README.md

@@ -1,6 +1,5 @@
 # VMware vRA Gem
 [![Gem Version](https://badge.fury.io/rb/vmware-vra.svg)](http://badge.fury.io/rb/vmware-vra)
-[![Build Status](https://travis-ci.org/chef-partners/vmware-vra-gem.svg?branch=master)](https://travis-ci.org/chef-partners/vmware-vra-gem)
 
 Client gem for interacting with VMware's vRealize Automation application.
 
@@ -16,6 +15,8 @@ to create Chef plugins for knife, test-kitchen, and provisioning.
 
 `2.0.0` version and forward will support vRA 7+.
 
+`3.0.0` version and forward will support vRA 8+.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -44,165 +45,134 @@ require 'vra'
 Then, set up your client object. You will need to know your tenant ID from your vRA administrator.
 
 ```
-vra = Vra::Client.new(username: 'devmgr@corp.local', password: 'mypassword', tenant: 'mytenant', base_url: 'https://vra.corp.local', verify_ssl: true)
+client = Vra::Client.new(username: 'devmgr@corp.local', password: 'mypassword', tenant: 'mytenant', base_url: 'https://vra.corp.local', verify_ssl: true)
 => #<Vra::Client:0x000000034c0df8 ... >
 ```
+### Catalog Types:
 
-To list all items in the catalog:
+To list all the catalog types:
 
 ```
-vra.catalog.all_items
-=> [{"@type"=>"CatalogItem", "id"=>"a9cd6148-6e0b-4a80-ac47-f5255c52b43d", "version"=>2, "name"=>"CentOS 6.6", "description"=>"Blueprint for deploying a CentOS Linux development server", ... }]
+client.catalog.all_types
+ => [#<Vra::CatalogType:0x00007fcde6855370 @id="com.vmw.vro.workflow", @data={"id"=>"com.vmw.vro.workflow", ... ]
 ```
 
-To only list the items in the catalog for which you are entitled to request:
+### Catalog Sources:
+
+To list all the catalog sources:
 
 ```
-vra.catalog.entitled_items
-=> [{"@type"=>"ConsumerEntitledCatalogItem", "catalogItem"=>{"id"=>"d29efd6b-3cd6-4f8d-b1d8-da4ddd4e52b1", "version"=>2, "name"=>"WindowsServer2012", "description"=>"Windows Server 2012", ... }]
+client.catalog.all_sources
+[#<Vra::CatalogSource:0x00007fcde3948c30 @id="2f5b2d5c-6dc2-4ea7-b304-cd8fea5ede0f", @data= ...]
 ```
 
-When you are ready to request an item from the catalog, create a new catalog request object:
+And to list the sources that are entitled only:
 
 ```
-catalog_request = vra.catalog.request('a9cd6148-6e0b-4a80-ac47-f5255c52b43d', cpus: 1, memory: 512, requested_for: 'devmgr@corp.local', lease_days: 30)
-=> #<Vra::CatalogRequest:0x00000003477c20 ... >
+client.catalog.entitled_sources(project_id)
+=> [#<Vra::CatalogSource:0x00007fcde2a28c00 @id="18102dc2-9e48-487a-93a8-aafab2ecc05 ...]
 ```
 
-To retrive catalog id from catalog name:
+Creating a new source can be done as follows:
 
 ```
-vra.catalog.fetch_catalog_items('my_catalog_name')
-=> #<Vra::CatalogRequest:0x00000004477c20 ... >  
+source = Vra::CatalogSource.create(client, name: 'New source', catalog_type_id: 'com.vmw.vro.workflow', project_id: project_id)
+ => #<Vra::CatalogSource:0x00007fad651f63b8 ... >
 ```
 
-vRA requires your sub-tenant (a.k.a. "business group") to be specified when requesting an item from the catalog. If the catalog item you are requesting is specifically created for a given business group, the gem will use that ID automatically without you needing to specify it.
+### Catalog Items
 
-An easier option has been provided to end user to provide a friendly sub-tenant name instead of sub-tenant id, and the driver would take care of retrieving the sub-tenant id for the corresponding sub-tenant name. Tenant name is also required along with sub-tenant name to retrieve sub-tenant id. 
-
-To retrieve sub-tenant id from sub-tenant name:
+To list all items in the catalog:
 
 ```
-vra.fetch_subtenant_items('my_tenant', 'my_subtenant_name')
+client.catalog.all_items
+ => [#<Vra::CatalogItem:0x00007fe583863b28>, #<Vra::CatalogItem:0x00007fe583863ad8 ... ]
 ```
 
-However, if there is no sub-tenant ID or sub-tenant name available for us to use, you will receive an error when you submit:
+To only list the items in the catalog for which you are entitled to request:
 
 ```
-request = catalog_request.submit
-ArgumentError: Unable to submit request, required param(s) missing => subtenant_id
-	from /home/aleff/vmware-vra/lib/vra/catalog_request.rb:42:in `validate_params!'
-	from /home/aleff/vmware-vra/lib/vra/catalog_request.rb:99:in `submit'
-	from (irb):4
-	from /opt/chefdk/embedded/bin/irb:11:in `<main>'
-
+client.catalog.entitled_items(project_id)
+=> [#<Vra::CatalogItem:0x00007fe583863b28>, #<Vra::CatalogItem:0x00007fe583863ad8 ... ]
 ```
 
-In this case, you will need to supply the sub-tenant ID manually:
+To retrive catalog id from catalog name:
 
 ```
-catalog_request.subtenant_id = '5327ddd3-1a4e-4663-9e9d-63db86ffc8af'
-=> "5327ddd3-1a4e-4663-9e9d-63db86ffc8af"
+client.catalog.fetch_catalog_items('centos')
+ =>
+[#<Vra::CatalogItem:0x00007fb734110f60
+  @id="f2e8c6ee-dd00-32c4-94c7-0a50046cb2f3",
+  @data={
+    "name"=>"oe-centos-1633598756_bp",
+  ...>
+]
 ```
 
-If your catalog blueprint item requires additional parameters to successfully submit your request, you may add them:
+### Requesting Deployments
+When you are ready to request a deployment using a catalog, create a new deployment object:
 
 ```
-catalog_request.set_parameter('my_parameter', 'string', 'my value')
+request = client.catalog.request(
+  catalog_id, 
+  image_mapping: 'VRA-nc-lnx-ce8.4-Docker',
+  flavor_mapping: 'Small',
+  name: 'CentOS VRA8 Test',
+  project_id: project_id,
+  version: '1'
+)
+ =>
+#<Vra::DeploymentRequest:0x00007fb7340b7438
+...
 ```
+To 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. 
+The ID of the catalog item from which you are requesting the deployment should be also included, and the version of the released cloud template. 
+Additionally, the name of the deployment should be specified and it should be unique.
+The image mapping specifies the OS image for a VM and the flavor mapping specifies the CPU count and RAM of a VM.
 
-If you need to set a parameter on a child object in the blueprint, you can add them by using a ~:
+If your catalog blueprint item requires additional parameters to successfully submit your request, you may add them:
 
 ```
-catalog_request.set_parameter('object~my_parameter', 'string', 'my value')
+request.set_parameter('my_parameter', 'string', 'my value')
 ```
 
-### Creating a request from a yaml or json payload
-Should you want to create a request ahead of time you can create the parameters up front by
-reading from a file or a hard coded payload you use every time.  This is not required by any means but allows
-for some extra flexibility when using this request object directly.  The only difference is that you can pass
-in the request parameters instead of having to set them after you create the object.
-
-Given a sample request object like the following you will want to read the yaml into an ruby object:
+### Managing the deployment
 
-```yaml
-requestData:
-  entries:
-    key: provider-provisioningGroupId
-    value:
-      type: string
-      value: 93992-3929392-32323828-832882394
-    key: provider-datacenter
-      type: string
-      value: datacenter1
-    key: provider-domain
-      type: string
-      value: chef.com
+Now, submit your request!  The client will return a new "Deployment" object you can use to query for status.
 
 ```
+deployment = catalog_request.submit
+=> #<Vra::Deployment:0x000000027caea0 ... >
 
-And now use that data to create the Vra::RequestParameters to feed into the catalog request.
-
-```ruby
-# read in the request data
-yaml_data = YAML,load(data)
-# create a parameters array, although this only works with VRA6, since VRA7 can have complex data
-parameters = yaml_data['requestData']['entries'].map {|item| [item['key'], item['value'].values].flatten }
-# We put the values in a array so we can easily explode the parameters using the splat operator later
-request_params = Vra::RequestParameters.new
-# loop through each parameter and setting each parameter
-parameters.each {|p| request_params.set(*p)  # splat
-request_options = {
-  cpus: 1,
-  memory: 1024,
-  requested_for: 'me@me.com',
-  lease_days: 2,
-  additional_params: request_params
-}
-# create the request
-catalog_request = vra.catalog.request(blueprint, request_options)
-```
-
-Now, submit your request!  The client will return a new "Request" object you can use to query for status.
-
-```
-request = catalog_request.submit
-=> #<Vra::Request:0x000000027caea0 ... >
-
-request.status
+deployment.status
 => "IN_PROGRESS"
 ```
 
-You can easily refresh your request object to get the latest status:
+You can refresh your deployment object to get the latest status:
 
 ```
-request.refresh && request.status
+deployment.refresh && deployment.status
 => "SUCCESSFUL"
-
-request.completion_state
-=> "SUCCESSFUL"
-
-request.completion_details
-=> "Request succeeded. Created hol-dev-32."
 ```
 
-You can also save the request ID for later, and create a new request object at your leisure to follow-up on your request:
+You can also save the deployment ID for later, and create a new deployment object at your leisure to follow-up on your deployment request:
 
 ```
-request.id
+deployment.id
 => "aed22465-02db-481d-b55a-cefe216096a2"
 
-new_request = vra.requests.by_id('aed22465-02db-481d-b55a-cefe216096a2')
-=> #<Vra::Request:0x0000000564ac30 ... >
+new_deployment = client.deployments.by_id('aed22465-02db-481d-b55a-cefe216096a2')
+=> #<Vra::Deployment:0x0000000564ac30 ... >
 
-new_request.status
-=> "SUCCESSFUL"
+new_deployment.status
+=> "CREATE_SUCCESSFUL"
 ```
 
-When the 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:
+### Deployment Resources
+When 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:
 
 ```
-resource = request.resources.first
+resource = deployment.resources.first
 => #<Vra::Resource:0x00000006772e68 ... >
 
 resource.network_interfaces
@@ -215,23 +185,26 @@ resource.name
 => "hol-dev-32"
 ```
 
-And just like requests, you can save the resource ID and query it again later:
+If you have the resource_id and the deployment object, you can fetch the resources details as follows
 
 ```
 resource.id
 => "331fd10b-f2a2-40ae-86bc-1255c1ee9a6d"
 
-new_resource = vra.resources.by_id('331fd10b-f2a2-40ae-86bc-1255c1ee9a6d')
+new_resource = deployment.resource_by_id('331fd10b-f2a2-40ae-86bc-1255c1ee9a6d')
 => #<Vra::Resource:0x000000067c13b0 ... >
 
 new_resource.name
 => "hol-dev-32"
 ```
 
-When you no longer need the VM, you can destroy it, which returns another request object you can query for status:
+### Deleting a deployment from vRA
+
+When you no longer need the VM, you can destroy the deployment which will delete all the associated resources as well. 
+The method will return a request object you can query for status:
 
 ```
-destroy_req = resource.destroy
+destroy_req = deployment.destroy
 => #<Vra::Request:0x00000006ea90d8 ... >
 
 destroy_req.status
@@ -241,66 +214,43 @@ destroy_req.status
 You can also list all resources and requests you have permission to see with these methods:
 
 ```
-vra.resources.all_resources
-vra.requests.all_requests
+deployment.resources
+deployment.requests
 ```
 
-### Download VRA catalog templates
-It can be quite useful to download the catalog templates from your VRA server for future playback or inspection.  This
-can now be easily done with some helpful class methods.
-
-To get a json string representation of the catalog template you can use `Vra::CatalogItem.dump_template(client, catalog_id)`
-
-To dump the catalog template to a file instead of a string `Vra::CatalogItem.write_template(client, catalog_id)`.  This will create a file like `windows2012.json`.
-
-If you just want to dump all the templates you can use `Vra::CatalogItem.dump_templates(client)`.  This will create a directory named vra_templates
-with all the entitled templates for the current user.  
-
-There are additional options you can provide to these methods in order to customize output file names and directories, so please see the source code in lib/vra/catalog_item.rb
-
-### Supply custom VRA catalog template and create request
-If you previously had some custom templates already in JSON format you can now use those to create requests instead of setting
-a bunch of parameters.  This can be especially useful when your request has complex parameters or you have a bunch of templates
-that you want to create unique requests for.
+### Pagination
 
-To use you can do something like:
+vRA 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:
 
 ```ruby
-payload_file = '/tmp/windows_2012.json'  # must be in json format
-cr = Vra::CatalogRequest.request_from_payload(client, payload_file)
-cr.submit
-
+vra = Vra::Client.new(username: 'devmgr@corp.local', password: 'mypassword', tenant: 'mytenant', base_url: 'https://vra.corp.local', verify_ssl: true, page_size: 100)
 ```
 
-If you already have a catalog request object you can still supply a custom payload by simply setting the template_payload property.
-Note this custom payload will be merged with the properties originally set when creating the catalog request object.
+... or setting `page_size` on the client object after you've created it:
 
 ```ruby
-cr = Vra::CatalogRequest.new(id, opts)
-cr.template_payload = File.read('/tmp/windows_2012.json')
-cr.submit
-
+client.page_size = 100
 ```
 
-### Pagination
+### Debugging
 
-vRA 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:
+To 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.
 
+MacOS/Linux:
 ```ruby
-vra = Vra::Client.new(username: 'devmgr@corp.local', password: 'mypassword', tenant: 'mytenant', base_url: 'https://vra.corp.local', verify_ssl: true, page_size: 100)
+export VRA_HTTP_TRACE=1
 ```
 
-... or setting `page_size` on the client object after you've created it:
-
-```ruby
-client.page_size = 100
+Windows:
+```powershell
+$env:VRA_HTTP_TRACE=1
 ```
 
 ## License and Authors
 
 Author:: Chef Partner Engineering (<partnereng@chef.io>)
 
-Copyright:: Copyright (c) 2015-2016 Chef Software, Inc.
+Copyright:: Copyright (c) 2022 Chef Software, Inc.
 
 License:: Apache License, Version 2.0
 

data/Rakefile

@@ -9,15 +9,4 @@ RuboCop::RakeTask.new do |task|
   task.options << "--display-cop-names"
 end
 
-begin
-  require "github_changelog_generator/task"
-
-  GitHubChangelogGenerator::RakeTask.new :changelog do |config|
-    config.future_release = Vra::VERSION
-    config.issues = true
-  end
-rescue LoadError
-  puts "github_changelog_generator is not available. gem install github_changelog_generator to generate changelogs"
-end
-
-task default: [ :spec, :rubocop ]
+task default: %i{spec rubocop}

data/lib/vra/catalog.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 #
 # Author:: Chef Partner Engineering (<partnereng@chef.io>)
-# Copyright:: Copyright (c) 2015 Chef Software, Inc.
+# Copyright:: Copyright (c) 2022 Chef Software, Inc.
 # License:: Apache License, Version 2.0
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -25,22 +25,53 @@ module Vra
       @client = client
     end
 
+    def all_types
+      fetch_resources Vra::CatalogType
+    end
+
+    def all_sources
+      fetch_resources Vra::CatalogSource
+    end
+
     def all_items
-      client.http_get_paginated_array!("/catalog-service/api/consumer/catalogItems")
-            .map! { |x| Vra::CatalogItem.new(client, data: x) }
+      fetch_resources Vra::CatalogItem
+    end
+
+    def entitled_sources(project_id)
+      fetch_entitlements(project_id, 'CatalogSourceIdentifier')
     end
 
-    def entitled_items
-      client.http_get_paginated_array!("/catalog-service/api/consumer/entitledCatalogItems")
-            .map! { |x| Vra::CatalogItem.new(client, data: x["catalogItem"]) }
+    def entitled_items(project_id)
+      fetch_entitlements(project_id, 'CatalogItemIdentifier')
     end
 
     def request(*args)
-      Vra::CatalogRequest.new(@client, *args)
+      Vra::DeploymentRequest.new(@client, *args)
     end
 
     def fetch_catalog_items(catalog_name)
-      client.http_get("/catalog-service/api/consumer/entitledCatalogItemViews?%24filter=name+eq+'#{catalog_name}'")
+      fetch_resources(
+        Vra::CatalogItem,
+        '/catalog/api/admin/items',
+        "search=#{catalog_name}"
+      )
+    end
+
+    private
+
+    def fetch_resources(klass, url = nil, filter = nil)
+      client
+        .http_get_paginated_array!(url || klass::INDEX_URL, filter)
+        .map! { |x| klass.new(client, data: x) }
+    end
+
+    def fetch_entitlements(project_id, type)
+      klass = type == 'CatalogSourceIdentifier' ? Vra::CatalogSource : Vra::CatalogItem
+
+      client
+        .get_parsed("/catalog/api/admin/entitlements?projectId=#{project_id}")
+        .select { |x| x['definition']['type'] == type }
+        .map! { |x| klass.new(client, data: x['definition']) }
     end
   end
 end

data/lib/vra/catalog_base.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+#
+# Author:: Ashique Saidalavi (<ashique.saidalavi@progress.com>)
+# Copyright:: Copyright (c) 2022 Chef Software, Inc.
+# License:: Apache License, Version 2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+module Vra
+  # Base class with common methods
+  class CatalogBase
+    attr_reader :id
+
+    # @param client [Vra::Client] - a vra client object
+    # @param opts [Hash] - Contains the either id of the catalog or the data hash
+    # Either one of id or data hash is required, must not supply both
+    def initialize(client, opts)
+      @client = client
+      @id     = opts[:id]
+      @data   = opts[:data]
+    end
+
+    def entitle!(opts = {})
+      response = client.http_post(
+        "/catalog/api/admin/entitlements?project_id=#{project_id}",
+        FFI_Yajl::Encoder.encode(entitle_params(opts[:type])),
+        opts[:skip_auth] || false
+      )
+
+      FFI_Yajl::Parser.parse(response.body)
+    end
+
+    private
+
+    attr_reader :client, :data
+
+    def validate!
+      raise ArgumentError, 'must supply id or data hash' if @id.nil? && @data.nil?
+      raise ArgumentError, 'must supply id or data hash, not both' if !@id.nil? && !@data.nil?
+    end
+
+    def entitle_params(type)
+      {
+        'projectId': project_id,
+        'definition': {
+          'type': type,
+          'id': id
+        }
+      }
+    end
+  end
+end