Overview

Skill Level: Any Skill Level

When there is a requirement to change the User Registry on APIC, there is currently no way to switch the user reg used when a user is established. Therefore, you must restore to factory default settings.

Ingredients

Step-by-step

  1. Summary

    When a user is established to the user registry used for the CMC, APIM, or Dev Portal Site, you cannot remove. Therefore, you will have to completely destroy and re-build. Until the RFE: Changing the user registry or owner is put into place, the way to change an established user registry will be to clean out the config (for cmc/apim) or create a new catalog (for dev portal site).

    Please vote for this RFE: https://www.ibm.com/developerworks/rfe/execute?use_case=viewRfe&CR_ID=94672 

    and https://www.ibm.com/developerworks/rfe/execute?use_case=viewRfe&CR_ID=91661 

    A “system clean apiconfig” means you will lose all your configured topology, organizations, Products, and API configurations from the management server.

    Therefore, you must ensure the following before executing the command:

    1. backup all your Products and APIs (this document will go over how to do that)
    2. ensure a backup of the management server is made just in case you need to revert back for any reason
    3. ensure that the portal server sites are all backed up
    4. must have the networking details (IP, netmask, gateway, etc) of the previous management server because this will be re-configured
    5. ensure your have a screen shot of the members and organizations the cmc currently contains
    6. ensure that all the certificates you have set up in the TLS profile is available because they will have to be recreated

    NOTICE: If you already have LDAP set as the user registry, and only need to update parameters in the user registry, this may be done with the exception that the Prefix and Suffix may not be changed; the other LDAP parameters may be changed.

  2. Backup Products and APIs (WebUI)

    Note: If you have a few Products and APIs, using the WebUI method is fine, but the APIC Toolkit can pull all your Products and APIs in bulk.

    Please see the next section for the APIC Toolkit method to pull the Products and APIs in bulk.

    NOTICE:

    • If you have your management servers in HA, ensure you take the exports from the primary server. To find out which is the primary server, log into the mgmt server and issue the ha list¬†command.
    • If you have multiple provider organizations, ensure you create a folder on your local system to store these backups so you know which Products and APIs below to which provider organization.

     

    1. Log into your APIM environment (https://<APIC_Mgmt_Svr_URL>/apim).

    2. Navigate to the Product you would like to export.

    3. Click on the upper right vertical ellipsis icon and select Download:

    downloadProduct

    4. Choose a file directory to download the Product.

    5. Click on the API associated to the Product and you will need to download the assocaited APIs to the same directory.

    API

    6. In the API you would like to export, click on the upper right vertical ellipsis and select Download.

    downloadAPI

    Now repeat the steps to manually download the Products and APIs for each provider organization you have.

     

  3. Backup Products and APIs (APIC Toolkit)

    For this example, I will be using the APIC Toolkit to download multiple Products and APIs at once.

    productsList apisList

    NOTICE:

    • If you have your management servers in HA, ensure you take the exports from the primary server. To find out which is the primary server, log into the mgmt server and issue the ha list command.
    • If you have multiple provider organizations, ensure you create a folder on your local system to store these backups so you know which Products and APIs below to which provider organization.

    1. Open your command line interface window and navigate to the folder you would like all the Products and APIs to download to, then issue apic login to log into your APIM.

    login

    2. Issue apic drafts:clone -s <your_APIC_URL> -o <your_Provider_Organization_Name_NOT_the_Display_Name> to download all the Products and APIs in the selected provider organization. NOTICE: You may get a false error message noting that you do not have permission if you enter in the organization name incorrectly, ensure that you have not input the display name.

    Note: -s is for server, -o is for organization

    downloaded

    As you can see all the Products and APIs are downloaded and ready to be uploaded.

  4. Backup APIC Mgmt Server & Portal Site Sample

    Backup of Mgmt Server

    1. Log into the APIC Management Server and issue

    config save apiconfig ftp <ftp_server_url> user <user_of_FTP_account> file <unique_name_of_file>.img

    apicBackup

    Backup of Portal Site

    1. Log into the Developer Portal and issue list_sites.

    2. Issue the backup_site -u <URL_of_the_site> command for each site you would like to backup.

    siteBackup

  5. Restore APIC in order to change User Registry

    WARNING: Before continuing you will be losing your provider organization, which means you will have to recreate your catalogs, therefore taking a screen shot of what is published will help with the republishing of the artifacts later. Also ensure that you capture the list of Members, provider organizations, and TLS profiles as mentioned in the summary.

    When ready, log into the APIC management server and issue the restore command:

    system clean apiconfig

    apiconfig

    Once the Management Server comes back up, you will have cleared the topology, organizations, Products, and API configuration from the management server, therefore will need to restore the following:

    • SMTP configuration (located in the Settings)
    • Members for the CMC (if any, located in the CMC Members tab).
    • Set the Developer Portal (in the Settings) –> Emsure that the rsa keys match.
    • Provider Organizations (located in the CMC Organizations tab).
    • Re-add any secondary management servers and DataPower gateways (located in the CMC Services tab).
    • After recreating the Provider Organizations, configure the members of the those organizations (located in each organization under the Menu > Admin > Members section).
    • The Catalogs, the portal site for the catalogs, and any additional users in the Users section.

     

    This is not needed, but in case network configurations were disrupted for any reason, here are the network set configurations to re-establish network:

    net set eth0 address <mgmt_server_address> mask <subnet_address>

    net set hostname static <hostname>

    net set domain static <domain>

    net set gateway static <gateway_url> eth0

    net set nameserver static <IP_of_nameservers> (space deliminated for multiple servers)

    net set ntp static <ntp_server>

    time set zone <time_zone> (example: America/Los_Angeles or America/New_York)

    net set search none

    net restart

  6. Restore DRAFTS

    You may restore the drafts in two ways:

    1. Through the webui by importing each and every Product and API

    imports

    2. or through the APIC Toolkit with the command apic drafts:push <product_or_API_filename> -s <your_APIC_URL> -o <your_Provider_Organization>

    NOTE: Pushing Products will also push APIs associated with the Product, but if there are any APIs which are not associated to any Products, these will have to be individually pushed.

    The diagram below shows the successful import of the sampleproduct1_product_1.0.0.yaml with it’s assocaited API into an empty organization (note: the org does not have to be empty).

    toolkitimport

    NOTE: These are drafts and are not published.

    If you would like to use the Toolkit to stage and publish after importing, you may issue the following command:

    apic drafts:publish <Products_name_as_displayed_in_products_draft> -s <your_APIC_URL> -o <your_Provider_Organization> -c <catalog_short_name>

    Note: -s is for server, -o is for organization, and -c is for catalog.

    publish

     

    Once everything is published test out the APIs.

5 comments on"API Connect v5: Changing User Registries"

  1. DipaliDarji July 12, 2017

    When nice and Detailed recipe. Thank you William

  2. Thank you Will, this has been very helpful for customers

  3. RaviRamnarayan October 13, 2017

    Thanks, Will. Clear and concise.

  4. U65D_Lorenzo_Monaco February 07, 2018

    Dear Will, what about client-id and secrets from application subscribed to plan/products? Do they need to be recreated?

    • @U65D_Lorenzo_Monaco the applications are picked up from the catalogs, do after the restore on the management server, you will see that in the Community section of the perspective Catalogs show all the applications, in which should reflect in the portal site once the portal site is restored.

Join The Discussion