Skip to content

Commit

Permalink
chore(docs): Translate doc structure for compatibility with doctool a…
Browse files Browse the repository at this point in the history 
…nd upgrade bootstrap workflow
  • Loading branch information
@m8rmclaren
m8rmclaren committed Jul 3, 2024
1 parent 9bad561 commit 6108d9c
Show file tree
Hide file tree
Showing 6 changed files with 271 additions and 190 deletions.
5 changes: 3 additions & 2 deletions ...orkflows/keyfactor-bootstrap-workflow.yml → .../workflows/keyfactor-release-workflow.yml
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
name: Keyfactor Bootstrap Workflow
name: Keyfactor Release Workflow

on:
workflow_dispatch:
Expand All @@ -11,9 +11,10 @@ on:

jobs:
call-starter-workflow:
uses: keyfactor/actions/.github/workflows/starter.yml@v2
uses: keyfactor/actions/.github/workflows/starter.yml@v3
secrets:
token: ${{ secrets.V2BUILDTOKEN}}
APPROVE_README_PUSH: ${{ secrets.APPROVE_README_PUSH}}
gpg_key: ${{ secrets.KF_GPG_PRIVATE_KEY }}
gpg_pass: ${{ secrets.KF_GPG_PASSPHRASE }}

179 changes: 68 additions & 111 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,145 +1,102 @@
<h1 align="center" style="border-bottom: none">
Google Cloud Provider Certificate Manager Universal Orchestrator Extension
</h1>

# Google Cloud Provider Certificate Manager
<p align="center">
<!-- Badges -->
<img src="https://img.shields.io/badge/integration_status-production-3D1973?style=flat-square" alt="Integration Status: production" />
<a href="https://github.com/Keyfactor/gcp-certmanager-orchestrator/releases"><img src="https://img.shields.io/github/v/release/Keyfactor/gcp-certmanager-orchestrator?style=flat-square" alt="Release" /></a>
<img src="https://img.shields.io/github/issues/Keyfactor/gcp-certmanager-orchestrator?style=flat-square" alt="Issues" />
<img src="https://img.shields.io/github/downloads/Keyfactor/gcp-certmanager-orchestrator/total?style=flat-square&label=downloads&color=28B905" alt="GitHub Downloads (all assets, all releases)" />
</p>

Google Certificate Manager Orchestrator for Add, Remove and Inventory.
<p align="center">
<!-- TOC -->
<a href="#support">
<b>Support</b>
</a>
·
<a href="#installation">
<b>Installation</b>
</a>
·
<a href="#license">
<b>License</b>
</a>
·
<a href="https://github.com/orgs/Keyfactor/repositories?q=orchestrator">
<b>Related Integrations</b>
</a>
</p>

#### Integration status: Production - Ready for use in production environments.

## About the Keyfactor Universal Orchestrator Extension
## Overview

This repository contains a Universal Orchestrator Extension which is a plugin to the Keyfactor Universal Orchestrator. Within the Keyfactor Platform, Orchestrators are used to manage “certificate stores” &mdash; collections of certificates and roots of trust that are found within and used by various applications.
The Google Cloud Provider (GCP) Certificate Manager Universal Orchestrator extension remotely manages certificates on the Google Cloud Platform Certificate Manager product. This extension facilitates three job types: Inventory, Management Add, and Management Remove. It supports adding certificates with private keys only.

The Universal Orchestrator is part of the Keyfactor software distribution and is available via the Keyfactor customer portal. For general instructions on installing Extensions, see the “Keyfactor Command Orchestrator Installation and Configuration Guide” section of the Keyfactor documentation. For configuration details of this specific Extension see below in this readme.
In the context of the GCP Certificate Manager, certificates are used to secure communications and authenticate identities for various services and applications. The GCP Certificate Manager simplifies the process of provisioning, managing, and deploying SSL/TLS certificates.

The Universal Orchestrator is the successor to the Windows Orchestrator. This Orchestrator Extension plugin only works with the Universal Orchestrator and does not work with the Windows Orchestrator.
Defined Certificate Stores of the Certificate Store Type represent a logical grouping or container of certificates that reside on the remote platform, in this case, the Google Cloud Platform. These Certificate Stores can include unbound certificates as well as certificates bound to existing map entries, enabling streamlined management of your certificates in the cloud environment.

## Support for Google Cloud Provider Certificate Manager
## Compatibility

Google Cloud Provider Certificate Manager is supported by Keyfactor for Keyfactor customers. If you have a support issue, please open a support ticket via the Keyfactor Support Portal at https://support.keyfactor.com
This integration is compatible with Keyfactor Universal Orchestrator version 10.4.1 and later.

###### To report a problem or suggest a new feature, use the **[Issues](../../issues)** tab. If you want to contribute actual bug fixes or proposed enhancements, use the **[Pull requests](../../pulls)** tab.
## Support
The Google Cloud Provider Certificate Manager Universal Orchestrator extension is supported by Keyfactor for Keyfactor customers. If you have a support issue, please open a support ticket with your Keyfactor representative. If you have a support issue, please open a support ticket via the Keyfactor Support Portal at https://support.keyfactor.com.

> To report a problem or suggest a new feature, use the **[Issues](../../issues)** tab. If you want to contribute actual bug fixes or proposed enhancements, use the **[Pull requests](../../pulls)** tab.
---
## Installation
Before installing the Google Cloud Provider Certificate Manager Universal Orchestrator extension, it's recommended to install [kfutil](https://github.com/Keyfactor/kfutil). Kfutil is a command-line tool that simplifies the process of creating store types, installing extensions, and instantiating certificate stores in Keyfactor Command.


---
1. Follow the [requirements section](docs/gcpcertmgr.md#requirements) to configure a Service Account and grant necessary API permissions.

<details><summary>Requirements</summary>

No requirements found

## Keyfactor Version Supported

The minimum version of the Keyfactor Universal Orchestrator Framework needed to run this version of the extension is 10.4.1
## Platform Specific Notes

The Keyfactor Universal Orchestrator may be installed on either Windows or Linux based platforms. The certificate operations supported by a capability may vary based what platform the capability is installed on. The table below indicates what capabilities are supported based on which platform the encompassing Universal Orchestrator is running.
| Operation | Win | Linux |
|-----|-----|------|
|Supports Management Add|&check; |&check; |
|Supports Management Remove|&check; |&check; |
|Supports Create Store| | |
|Supports Discovery| | |
|Supports Reenrollment| | |
|Supports Inventory|&check; |&check; |
</details>

2. Create Certificate Store Types for the Google Cloud Provider Certificate Manager Orchestrator extension.

* **Using kfutil**:

```shell
# GCP Certificate Manager
kfutil store-types create GcpCertMgr
```

* **Manually**:
* [GCP Certificate Manager](docs/gcpcertmgr.md#certificate-store-type-configuration)

---
3. Install the Google Cloud Provider Certificate Manager Universal Orchestrator extension.

* **Using kfutil**: On the server that that hosts the Universal Orchestrator, run the following command:

```shell
# Windows Server
kfutil orchestrator extension -e gcp-certmanager-orchestrator@latest --out "C:\Program Files\Keyfactor\Keyfactor Orchestrator\extensions"
## Google Cloud Platform Certificate Manager
# Linux
kfutil orchestrator extension -e gcp-certmanager-orchestrator@latest --out "/opt/keyfactor/orchestrator/extensions"
```

**Overview**
* **Manually**: Follow the [official Command documentation](https://software.keyfactor.com/Core-OnPrem/Current/Content/InstallingAgents/NetCoreOrchestrator/CustomExtensions.htm?Highlight=extensions) to install the latest [Google Cloud Provider Certificate Manager Universal Orchestrator extension](https://github.com/Keyfactor/gcp-certmanager-orchestrator/releases/latest).

The GCP Certificate Manager Orchestrator Extension remotely manages certificates on the Google Cloud Platform Certificate Manager Product
4. Create new certificate stores in Keyfactor Command for the Sample Universal Orchestrator extension.

This orchestrator extension implements three job types – Inventory, Management Add, and Management Remove. Below are the steps necessary to configure this Orchestrator Extension. It supports adding certificates with private keys only. The GCP Certificate Manager Orchestrator Extension supports the replacement of unbound certificates as well as certificates bound to existing map entries, but it does **not** support specifying map entry bindings when adding new certificates.
* [GCP Certificate Manager](docs/gcpcertmgr.md#certificate-store-configuration)


**Google Cloud Configuration**

1. Read up on [Google Certificate Manager](https://cloud.google.com/certificate-manager/docs) and how it works.
## License

2. Either a Google Service Account is needed with the following permissions (Note: Workload Identity Management Should be used but at the time of the writing it was not available in the .net library yet), or the virtual machine running the Keyfactor Orchestrator Service must reside within Google Cloud.
![](images/ServiceAccountSettings.gif)

3. The following Api Access is needed:
![](images/ApiAccessNeeded.gif)

4. If authenticating via service account, download the Json Credential file as shown below:
![](images/GoogleKeyJsonDownload.gif)


## Keyfactor Command Configuration

**1. Create the New Certificate Store Type for the GCP Certificate Manager Orchestrator**

In Keyfactor Command create a new Certificate Store Type similar to the one below:

#### STORE TYPE CONFIGURATION
SETTING TAB | CONFIG ELEMENT | DESCRIPTION
------|-----------|------------------
Basic |Name |Descriptive name for the Store Type. Example: Google Cloud Certificate Manager
Basic |Short Name |The name that identifies the registered functionality of the orchestrator. Must be GcpCertMgr
Basic |Custom Capability|Unchecked
Basic |Job Types |Inventory, Add, and Remove are the supported job types
Basic |Needs Server |Unchecked
Basic |Blueprint Allowed |Unchecked
Basic |Requires Store Password |Unchecked
Basic |Supports Entry Password |Unchecked
Advanced |Store Path Type| Fixed
Advanced |Store Path Type Value (the textbox that appears below Store Path Type when Store Path Type is set to "Fixed") |n/a
Advanced |Supports Custom Alias |Required
Advanced |Private Key Handling |Required
Advanced |PFX Password Style |Default
Custom Fields|Google Cloud Platform Project Location/Region|Name:Location, Display Name:Location, Type:String, Default Value:global, Required:False
Custom Fields|The file name of the Google Cloud Service Account Key File installed in the same folder as the orchestrator extension. Empty if the orchestrator server resides in GCP and you are not using a service account key |Name:Service Account Key File Name, Type:String, Default Value: (leave blank), Required:True
Entry Parameters|N/A| There are no Entry Parameters

**Basic Settings:**

![](images/CertStoreType-Basic.gif)

**Advanced Settings:**

![](images/CertStoreType-Advanced.gif)

**Custom Fields:**

![](images/CertStoreType-CustomFields.gif)
![](images/CertStoreType-CustomField-Location.gif)
![](images/CertStoreType-CustomField-ServiceAccountKey.gif)

**Entry Params:**

![](images/CertStoreType-EntryParameters.gif)

**2. Register the GCP Certificate Manager Orchestrator with Keyfactor**
See Keyfactor InstallingKeyfactorOrchestrators.pdf Documentation. Get from your Keyfactor contact/representative.

**3. Create a GCP Certificate Manager Certificate Store within Keyfactor Command**
In Keyfactor Command create a new Certificate Store similar to the one below

![](images/CertStoreSettings.gif)

#### STORE CONFIGURATION
CONFIG ELEMENT |DESCRIPTION
----------------|---------------
Category |The type of certificate store to be configured. Select category based on the display name configured above "GCP Certificate Manager".
Container |This is a logical grouping of like stores. This configuration is optional and does not impact the functionality of the store.
Client Machine |Your GCP Project ID for your account.
Store Path |This is not used and should be defaulted to n/a per the certificate store type set up.
Orchestrator |This is the orchestrator server registered with the appropriate capabilities to manage this certificate store type.
Location|**global** is the default but could be another region based on the project.
Service Account Key File Name | The name of the file containing the GCP Service Account JSON formatted key previously downloaded. Keep this optional field blank if the Keyfactor Orchestrator Service is running from an authenticated VM within Google Cloud.
Update Server User Name |Click and select No Value.
Update Server Password |Click and select No Value.
Use SSL |This should be checked.
Inventory Schedule |The interval that the system will use to report on what certificates are currently in the store.



When creating cert store type manually, that store property names and entry parameter names are case sensitive
Apache License 2.0, see [LICENSE](LICENSE).

## Related Integrations

See all [Keyfactor Universal Orchestrator extensions](https://github.com/orgs/Keyfactor/repositories?q=orchestrator).
Loading

0 comments on commit 6108d9c

Please sign in to comment.