Merge pull request #102 from jfrog/GH-101-add-import-doc

GH-101 add import documentation.

CHANGELOG.md

@@ -1,3 +1,11 @@
+## 1.9.9 (January 31, 2023). Tested on Artifactory 7.49.6 and Xray 3.65.3
+
+IMPROVEMENTS:
+
+* added import instructions to all the provider resources.
+ Issue [#101](https://github.com/jfrog/terraform-provider-xray/issues/101)
+ PR [#102](https://github.com/jfrog/terraform-provider-xray/pull/102) 
+
 ## 1.9.8 (January 19, 2023). Tested on Artifactory 7.49.5 and Xray 3.65.2
 
 BUG FIXES:

docs/resources/ignore_rule.md

@@ -16,12 +16,12 @@ Provides an Xray ignore rule resource. See [Xray Ignore Rules](https://www.jfrog
 resource "xray_ignore_rule" "ignore-rule-5649816" {
   notes           = "notes"
   cves            = ["fake-cves", "cves-1"]
-  expiration_date = "2023-01-25"
+  expiration_date = "2023-10-25"
 }
 
 resource "xray_ignore_rule" "ignore-rule-2195938" {
   notes           = "notes"
-  expiration_date = "2023-01-19"
+  expiration_date = "2023-10-19"
   vulnerabilities = ["any"]
 
   build {
@@ -32,14 +32,26 @@ resource "xray_ignore_rule" "ignore-rule-2195938" {
 
 resource "xray_ignore_rule" "ignore-rule-2590577" {
   notes           = "notes"
-  expiration_date = "2023-01-19"
+  expiration_date = "2023-10-19"
   vulnerabilities = ["any"]
 
   component {
     name    = "name"
     version = "version"
   }
 }
+
+resource "xray_ignore_rule" "ignore-111" {
+  notes            = "fake notes"
+  expiration_date  = "2024-01-02"
+  vulnerabilities  = ["any"]
+
+  artifact {
+    name    = "fake-name"
+    version = "fake-version"
+    path    = "invalid-path/"
+  }
+}
 ```
 
 <!-- schema generated by tfplugindocs -->
@@ -56,7 +68,7 @@ resource "xray_ignore_rule" "ignore-rule-2590577" {
 - `component` (Block Set) List of specific components to ignore. Omit to apply to all. (see [below for nested schema](#nestedblock--component))
 - `cves` (Set of String) List of specific CVEs to ignore. Omit to apply to all.
 - `docker_layers` (Set of String) List of Docker layer SHA256 hashes to ignore. Omit to apply to all.
-- `expiration_date` (String) The Ignore Rule will be active until the expiration date. At that date it will automatically get deleted.
+- `expiration_date` (String) The Ignore Rule will be active until the expiration date. At that date it will automatically get deleted. The rule with the expiration date less than current day, will error out.
 - `licenses` (Set of String) List of specific licenses to ignore. Omit to apply to all.
 - `operational_risk` (List of String) Operational risk to ignore. Only accept 'any'
 - `policies` (Set of String) List of specific policies to ignore. Omit to apply to all.
@@ -118,4 +130,11 @@ Required:
 
 Optional:
 
-- `version` (String) Version of the release bundle
+- `version` (String) Version of the release bundle
+
+## Import
+
+Ignore rules can be imported using their IDs, e.g.
+```
+$ terraform import xray_ignore_rule.ignore-rule-2590577 44b273ac-dca3-42dc-6819-f70648c0b48e
+```

docs/resources/license_policy.md

@@ -159,4 +159,11 @@ Optional:
 Required:
 
 - `active` (Boolean) Whether or not to block download of artifacts that meet the artifact and severity `filters` for the associated `xray_watch` resource.
-- `unscanned` (Boolean) Whether or not to block download of artifacts that meet the artifact `filters` for the associated `xray_watch` resource but have not been scanned yet.
+- `unscanned` (Boolean) Whether or not to block download of artifacts that meet the artifact `filters` for the associated `xray_watch` resource but have not been scanned yet.
+
+## Import
+
+License policies can be imported using their names, e.g.
+```
+$ terraform import xray_license_policy.allowed_licenses test-license-policy-allowed
+```

docs/resources/licenses_report.md

@@ -2,8 +2,6 @@
 # generated by https://github.com/hashicorp/terraform-plugin-docs
 page_title: "xray_licenses_report Resource - terraform-provider-xray"
 subcategory: "Reports"
-description: |-
-  Creates Xray License Due Diligence report. The License Due Diligence report provides you with a list of components and artifacts and their relevant licenses. This enables you to review and verify that the components and artifacts comply with the license requirements. This report provides due diligence license related information on each component for a selected scope. Due diligence license information includes information such as unknown licenses and unrecognized licenses found in your components.
 ---
 
 # xray_licenses_report (Resource)
@@ -140,4 +138,9 @@ Optional:
 - `exclude_path_patterns` (Set of String) Exclude path patterns.
 - `include_path_patterns` (Set of String) Include path patterns.
 
+## Import
 
+License reports can be imported using their names, e.g.
+```
+$ terraform import xray_licenses_report.test-license-report report
+```

docs/resources/operational_risk_policy.md

@@ -2,8 +2,6 @@
 # generated by https://github.com/hashicorp/terraform-plugin-docs
 page_title: "xray_operational_risk_policy Resource - terraform-provider-xray"
 subcategory: "Policies"
-description: |-
-  Creates an Xray policy using V2 of the underlying APIs. Please note: It's only compatible with Bearer token auth method (Identity and Access => Access Tokens)
 ---
 
 # xray_operational_risk_policy (Resource)
@@ -174,4 +172,9 @@ Required:
 - `active` (Boolean) Whether or not to block download of artifacts that meet the artifact and severity `filters` for the associated `xray_watch` resource.
 - `unscanned` (Boolean) Whether or not to block download of artifacts that meet the artifact `filters` for the associated `xray_watch` resource but have not been scanned yet.
 
+## Import
 
+Operational risk policies can be imported using their names, e.g.
+```
+$ terraform import xray_operational_risk_policy.min_risk test-operational-risk-policy-min-risk
+```

docs/resources/operational_risks_report.md

@@ -2,8 +2,6 @@
 # generated by https://github.com/hashicorp/terraform-plugin-docs
 page_title: "xray_operational_risks_report Resource - terraform-provider-xray"
 subcategory: "Reports"
-description: |-
-  Creates Xray Operational Risks report. The Operational Risk report provides you with additional data on OSS components that will help you gain insights into the risk level of the components in use, such as; EOL, Version Age, Number of New Versions, and so on.  For more information, see Components Operational Risk https://www.jfrog.com/confluence/display/JFROG/Components+Operational+Risk
 ---
 
 # xray_operational_risks_report (Resource)
@@ -135,4 +133,9 @@ Optional:
 - `exclude_path_patterns` (Set of String) Exclude path patterns.
 - `include_path_patterns` (Set of String) Include path patterns.
 
+## Import
 
+Operational risk reports can be imported using their names, e.g.
+```
+$ terraform import xray_operational_risks_report.report test-operational-risks-report
+```

docs/resources/repository_config.md

@@ -2,8 +2,6 @@
 # generated by https://github.com/hashicorp/terraform-plugin-docs
 page_title: "xray_repository_config Resource - terraform-provider-xray"
 subcategory: ""
-description: |-
-  Provides an Xray repository config resource. See Xray Indexing Resources https://www.jfrog.com/confluence/display/JFROG/Indexing+Xray+Resources#IndexingXrayResources-SetaRetentionPeriod and REST API https://www.jfrog.com/confluence/display/JFROG/Xray+REST+API#XrayRESTAPI-UpdateRepositoriesConfigurations for more details.
 ---
 
 # xray_repository_config (Resource)
@@ -103,4 +101,9 @@ Optional:
 - `index_new_artifacts` (Boolean) If checked, Xray will scan newly added artifacts in the path. Note that existing artifacts will not be scanned. If the folder contains existing artifacts that have been scanned, and you do not want to index new artifacts in that folder, you can choose not to index that folder.
 - `retention_in_days` (Number) The artifact will be retained for the number of days you set here, after the artifact is scanned. This will apply to all artifacts in the repository.
 
+## Import
 
+Repository configs can be imported using their names, e.g.
+```
+$ terraform import xray_repository_config.xray-repo-config-pattern example-repo-local
+```

docs/resources/security_policy.md

@@ -164,4 +164,11 @@ Optional:
 Required:
 
 - `active` (Boolean) Whether or not to block download of artifacts that meet the artifact and severity `filters` for the associated `xray_watch` resource.
-- `unscanned` (Boolean) Whether or not to block download of artifacts that meet the artifact `filters` for the associated `xray_watch` resource but have not been scanned yet.
+- `unscanned` (Boolean) Whether or not to block download of artifacts that meet the artifact `filters` for the associated `xray_watch` resource but have not been scanned yet.
+
+## Import
+
+Security policies can be imported using their names, e.g.
+```
+$ terraform import xray_security_policy.min_severity test-security-policy-severity
+```

docs/resources/settings.md

@@ -28,4 +28,11 @@ resource "xray_settings" "db_sync" {
 
 ### Read-Only
 
-- `id` (String) The ID of this resource.
+- `id` (String) The ID of this resource.
+
+## Import
+
+Settings (currently only DB sync time) can be imported using their names, e.g.
+```
+$ terraform import xray_settings.db_sync db-time
+```

docs/resources/violations_report.md

@@ -2,8 +2,6 @@
 # generated by https://github.com/hashicorp/terraform-plugin-docs
 page_title: "xray_violations_report Resource - terraform-provider-xray"
 subcategory: "Reports"
-description: |-
-  Creates Xray Violations report. The Violations report provides you with information on security and license violations for each component in the selected scope. Violations information includes information such as type of violation, impacted artifacts, and severity.
 ---
 
 # xray_violations_report (Resource)
@@ -194,4 +192,9 @@ Optional:
 - `exclude_path_patterns` (Set of String) Exclude path patterns.
 - `include_path_patterns` (Set of String) Include path patterns.
 
+## Import
 
+Violations reports can be imported using their names, e.g.
+```
+$ terraform import xray_violations_report.report test-violations-report 
+```

docs/resources/vulnerabilities_report.md

@@ -2,8 +2,6 @@
 # generated by https://github.com/hashicorp/terraform-plugin-docs
 page_title: "xray_vulnerabilities_report Resource - terraform-provider-xray"
 subcategory: "Reports"
-description: |-
-  Creates Xray Vulnerabilities report. The Vulnerabilities report provides information about vulnerabilities in your artifacts, builds, and release bundles. In addition to the information provided in the JFrog Platform on each of these entities, the report gives you a wider range of information such as vulnerabilities in multiple repositories, builds and release bundles. Criteria such as vulnerable component, CVE, cvss score, and severity are available in the report.
 ---
 
 # xray_vulnerabilities_report (Resource)
@@ -169,4 +167,9 @@ Optional:
 - `exclude_path_patterns` (Set of String) Exclude path patterns.
 - `include_path_patterns` (Set of String) Include path patterns.
 
+## Import
 
+Vulnerabilities reports can be imported using their names, e.g.
+```
+$ terraform import xray_vulnerabilities_report.report test-vulnerabilities-report
+```

docs/resources/watch.md

@@ -352,4 +352,11 @@ Required:
 Optional:
 
 - `exclude_patterns` (List of String) The pattern will apply to the selected repositories. Simple comma separated wildcard patterns for repository artifact paths (with no leading slash). Ant-style path expressions are supported (*, **, ?). For example: 'org/apache/**'
-- `include_patterns` (List of String) The pattern will apply to the selected repositories. Simple comma separated wildcard patterns for repository artifact paths (with no leading slash). Ant-style path expressions are supported (*, **, ?). For example: 'org/apache/**'
+- `include_patterns` (List of String) The pattern will apply to the selected repositories. Simple comma separated wildcard patterns for repository artifact paths (with no leading slash). Ant-style path expressions are supported (*, **, ?). For example: 'org/apache/**'
+
+## Import
+
+Xray Watches can be imported using their names, e.g.
+```
+$ terraform import xray_watch.all-repos all-repos-watch
+```

docs/resources/workers_count.md

@@ -8,6 +8,8 @@ subcategory: "Workers Count"
 
 Provides an Xray Workers Count resource.
 
+~> Self-Hosted only.
+
 [Official documentation](https://www.jfrog.com/confluence/display/JFROG/Configuring+Xray#ConfiguringXray-AdvancedSettings).
 
 [API documentation](https://www.jfrog.com/confluence/display/JFROG/Xray+REST+API#XrayRESTAPI-ConfiguringtheWorkersCount).
@@ -107,3 +109,10 @@ Required:
 
 - `existing_content` (Number) Number of workers for existing content
 - `new_content` (Number) Number of workers for new content
+
+## Import
+
+Workers count resource can be imported using their names, e.g.
+```
+$ terraform import xray_workers_count.workers-count workers-count
+```

examples/resources/xray_ignore_rule/resource.tf

@@ -1,12 +1,12 @@
 resource "xray_ignore_rule" "ignore-rule-5649816" {
   notes           = "notes"
   cves            = ["fake-cves", "cves-1"]
-  expiration_date = "2023-01-25"
+  expiration_date = "2023-10-25"
 }
 
 resource "xray_ignore_rule" "ignore-rule-2195938" {
   notes           = "notes"
-  expiration_date = "2023-01-19"
+  expiration_date = "2023-10-19"
   vulnerabilities = ["any"]
 
   build {
@@ -17,11 +17,23 @@ resource "xray_ignore_rule" "ignore-rule-2195938" {
 
 resource "xray_ignore_rule" "ignore-rule-2590577" {
   notes           = "notes"
-  expiration_date = "2023-01-19"
+  expiration_date = "2023-10-19"
   vulnerabilities = ["any"]
 
   component {
     name    = "name"
     version = "version"
   }
+}
+
+resource "xray_ignore_rule" "ignore-111" {
+  notes            = "fake notes"
+  expiration_date  = "2024-01-02"
+  vulnerabilities  = ["any"]
+
+  artifact {
+    name    = "fake-name"
+    version = "fake-version"
+    path    = "invalid-path/"
+  }
 }

pkg/xray/resource_xray_ignore_rule.go

@@ -70,7 +70,7 @@ func resourceXrayIgnoreRule() *schema.Resource {
 				Optional:         true,
 				ForceNew:         true,
 				ValidateDiagFunc: validation.ToDiagFunc(validation.StringMatch(regexp.MustCompile(`^\d{4}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[0-1])$`), "Date must be in YYYY-MM-DD format")),
-				Description:      "The Ignore Rule will be active until the expiration date. At that date it will automatically get deleted.",
+				Description:      "The Ignore Rule will be active until the expiration date. At that date it will automatically get deleted. The rule with the expiration date less than current day, will error out.",
 			},
 			"author": {
 				Type:     schema.TypeString,

templates/resources/ignore_rule.md.tmpl

@@ -14,4 +14,11 @@ Provides an Xray ignore rule resource. See [Xray Ignore Rules](https://www.jfrog
 
 {{tffile "examples/resources/xray_ignore_rule/resource.tf"}}
 
-{{ .SchemaMarkdown | trimspace }}
+{{ .SchemaMarkdown | trimspace }}
+
+## Import
+
+Ignore rules can be imported using their IDs, e.g.
+```
+$ terraform import xray_ignore_rule.ignore-rule-2590577 44b273ac-dca3-42dc-6819-f70648c0b48e
+```

templates/resources/license_policy.md.tmpl

@@ -18,4 +18,11 @@ Please note: It's only compatible with Bearer token auth method (Identity and Ac
 
 {{tffile "examples/resources/xray_license_policy/resource.tf"}}
 
-{{ .SchemaMarkdown | trimspace }}
+{{ .SchemaMarkdown | trimspace }}
+
+## Import
+
+License policies can be imported using their names, e.g.
+```
+$ terraform import xray_license_policy.allowed_licenses test-license-policy-allowed
+```

templates/resources/licenses_report.md.tmpl

@@ -0,0 +1,22 @@
+---
+# generated by https://github.com/hashicorp/terraform-plugin-docs
+page_title: "xray_licenses_report Resource - terraform-provider-xray"
+subcategory: "Reports"
+---
+
+# xray_licenses_report (Resource)
+
+Creates Xray License Due Diligence report. The License Due Diligence report provides you with a list of components and artifacts and their relevant licenses. This enables you to review and verify that the components and artifacts comply with the license requirements. This report provides due diligence license related information on each component for a selected scope. Due diligence license information includes information such as unknown licenses and unrecognized licenses found in your components.
+
+## Example Usage
+
+{{tffile "examples/resources/xray_licenses_report/resource.tf"}}
+
+{{ .SchemaMarkdown | trimspace }}
+
+## Import
+
+License reports can be imported using their names, e.g.
+```
+$ terraform import xray_licenses_report.test-license-report report
+```