vmware-vra 2.7.1 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3e28bed631cab067e13738576e243460e12e5b4ab8421f984faf1261c5b70691
-  data.tar.gz: 1be855a3503c4a15386c885accdd75a8f5fc5fc13eb84abc82c91cfe08250b6a
+  metadata.gz: 55b844fe4edf716d4c6668cfa5c13721caa0f36a4873aae4f2949509cf6bfc1c
+  data.tar.gz: 5a68b428aa38c0e30a8ba89790ccdb5fd9b5d233485497886cd4d290f4f528d0
 SHA512:
-  metadata.gz: 300797ca6f9997718a76e9c86fd1ba9f898463a94ebc95dd8e626799e77bdd6e0cd0bec7a4290f5246c31dbebbed338c84941fc132fc71763b1d7bedd10c2b1d
-  data.tar.gz: 3d8e098691e4edadafa5b5c9b6768b267ad92ff5736aed899c31ed0f62969714f743f2f8cd2b96f6a23cab6fa83609810cdfd71860c7aaaf980bd8a60d25f7c9
+  metadata.gz: b41f6cf8aca5fde7912e59937a569af9b0fb550877a07eb1302edd94b02a3caac478ca41474786fbf2293c2a96fc3334440b0eb72784a7b48c41090a401a9f99
+  data.tar.gz: 3dfa51c5e343ca7994f9240afa7b6b2f81de243bd88de0b8a9f19f9d189d571a4d95d4fe00628950a50673e8e15f4f2b849cf78456edc8423ff20aa512a84eb8

data/.gitignore

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

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Change Log
 
+## [3.1.0](https://github.com/chef-partners/vmware-vra-gem/tree/v3.1.0) (2022-01-30)
+[Full Changelog](https://github.com/chef-partners/vmware-vra-gem/compare/v3.0.1...v3.1.0)
+
+- Make the version param optional in deployment request api 
+
+## [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)
 
@@ -298,4 +319,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,136 @@ 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. If the user doesn't specify a version explicitly, the latest version will be fetched automatically and will be used for the request.
+ 
+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.
+### Managing the deployment
 
-Given a sample request object like the following you will want to read the yaml into an ruby object:
-
-```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
-=> "SUCCESSFUL"
-
-request.completion_state
+deployment.refresh && deployment.status
 => "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 +187,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,45 +216,8 @@ 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
-```
-
-### 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.
-
-To use you can do something like:
-
-```ruby
-payload_file = '/tmp/windows_2012.json'  # must be in json format
-cr = Vra::CatalogRequest.request_from_payload(client, payload_file)
-cr.submit
-
-```
-
-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.
-
-```ruby
-cr = Vra::CatalogRequest.new(id, opts)
-cr.template_payload = File.read('/tmp/windows_2012.json')
-cr.submit
-
+deployment.resources
+deployment.requests
 ```
 
 ### Pagination
@@ -314,7 +252,7 @@ $env:VRA_HTTP_TRACE=1
 
 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