Skip to content

Commit eab9825

Browse files
adorton-adobeadorton-adobe
committed
publish upgrade guide
1 parent 05185c8 commit eab9825

File tree

2 files changed

+118
-3
lines changed

2 files changed

+118
-3
lines changed

‎en/success-guide/update_cert.md

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,14 @@
11
---
22
layout: default
33
lang: en
4-
nav_link: Update Certificates
4+
nav_link: Certificate Update
55
nav_level: 2
66
nav_order: 330
77
---
88

99
# Updating Public/Private Certificates
1010

11-
[Previous Section](scheduling.md) \| [Back to Contents](index.md)
11+
[Previous Section](scheduling.md) \| [Next Section](upgrading.md)
1212

1313
The [Adobe Developer Console certificates](setup_adobeio.md) you created during initial setup will eventually expire and
1414
need replacement. Adobe will notify all system admins for an organization when one or more certificates are set to expire.
@@ -25,7 +25,7 @@ You can generate a new public/private keypair in the Adobe Developer console. **
2525
privileges in the Admin Console organization associated with your keys.
2626

2727
1. Log into [Adobe Developer Console](https://developer.adobe.com/console)
28-
2. Make sure you select the correct organization in the dropdown menu in the upper-left-hand corner of the page
28+
2. Make sure you select the correct organization in the dropdown menu in the upper-right-hand corner of the page
2929
3. Click the "Projects" tab in the top navigation menu
3030
4. Click the card for the project associated with the credentials you wish to update
3131

@@ -69,3 +69,5 @@ Return to the [Adobe Developer Console](https://developer.adobe.com/console), op
6969
Service Account details, and click the trash icon next to the old public key.
7070

7171
![](images/delete_old_key.png)
72+
73+
[Previous Section](scheduling.md) \| [Next Section](upgrading.md)

‎en/success-guide/upgrading.md

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
---
2+
layout: default
3+
lang: en
4+
nav_link: Upgrade Guide
5+
nav_level: 2
6+
nav_order: 340
7+
---
8+
9+
# Upgrade From PEX to Binary
10+
{:."no_toc"}
11+
12+
## In This Section
13+
{:."no_toc"}
14+
15+
* TOC Placeholder
16+
{:toc}
17+
18+
---
19+
20+
[Previous Section](update_cert.md) \| [Back to Contents](index.md)
21+
22+
---
23+
24+
# Why Upgrade?
25+
26+
To ensure security and stability, the development team of the User Sync Tool does not support older versions of the Sync
27+
Tool. We encourage every user of the tool check for [new releases](https://github.com/adobe-apiplatform/user-sync.py/releases/latest)
28+
regularly and keep their User Sync Tool up-to-date.
29+
30+
Any User Sync Tool release prior to 2.6.0 is packaged as a [pex](https://github.com/pantsbuild/pex) file, which requires an
31+
external Python interpreter to run. To maximize compatibility, builds were targeted to Python 2.7 and Python 3.6 (or below).
32+
Starting with 2.6.0, the sync tool is built and distributed as a self-contained binary executable. This executable embeds its
33+
own Python environment, removing the requirement of an external Python interpreter.
34+
35+
This build model also makes it possible for the UST to be built with newer versions of Python. The executable build currently
36+
runs with Python 3.9 (as of version 2.6.5). Older versions of Python are either no longer maintained, or are
37+
[nearing end-of-life](https://endoflife.date/python).
38+
39+
The User Sync Tool also has many new features unavailable in older versions.
40+
41+
* Instant access to documentation - `./user-sync docs`
42+
* Security key generation - `./user-sync certgen`
43+
* Private key encryption and decryption - `./user-sync encrypt` and `./user-sync decrypt`
44+
* Template config generation - `./user-sync example-config`
45+
* LDAP Kerberos Support
46+
* Admin Console identity connector
47+
* Adobe Sign Sync capability
48+
* See the [changelog](https://raw.githubusercontent.com/adobe-apiplatform/user-sync.py/v2/.changelog/changelog.md) for more details
49+
50+
# Compatibility
51+
52+
The binary build of the UST has been tested on the supported versions of our targeted platforms (Windows, CentOS and Ubuntu). It is
53+
compatible with all major versions except for older Ubuntu LTS releases.
54+
55+
Neither the Bionic nor Focal builds will run on Ubuntu Trusty or Xenial because each of the former require newer versions of `libc`.
56+
It may be possible to upgrade libc and other system packages to get the tool running, but the UST development team will not be able to
57+
provide support.
58+
59+
The tool can also be built from source to run on unsupported platforms. See the [build instructions](https://github.com/adobe-apiplatform/user-sync.py#build-instructions)
60+
in the readme. Note that Python 3.9 is required to build the tool, which may need to be installed on the system (or built from source).
61+
62+
| Platform | Compatible? | Notes |
63+
|---|---|---|
64+
| Windows Server 2012R2 | Y | |
65+
| Windows Server 2016 | Y | |
66+
| Windows Server 2019 | Y | |
67+
| CentOS/RedHat Enterprise Linux 7 | Y | |
68+
| CentOS/RedHat Enterprise Linux 8 | Y | |
69+
| Ubuntu Trusty 12.04 | N | `bionic` or `focal` builds will not run on Trusty and it [isn't supported by our build system](https://github.com/actions/virtual-environments) |
70+
| Ubuntu Xenial 16.04 | N | `bionic` or `focal` builds will not run on Xenial and it [isn't supported by our build system](https://github.com/actions/virtual-environments) |
71+
| Ubuntu Bionic 18.04 | Y | Use `ubuntu-bionic` build |
72+
| Ubuntu Focal 20.04 | Y | Use `ubuntu-focal` build |
73+
{: .bordertablestyle }
74+
75+
# Basic Procedure
76+
77+
**Note:** If you run multiple sync processes (perhaps to sync from different identity sources), we recommend repeating this procedure
78+
for each sync config. You will not need to repeat steps 1 and 2 if each sync is run from the same root directory.
79+
80+
1. Download the [latest release](https://github.com/adobe-apiplatform/user-sync.py/releases/latest) for your platform.
81+
2. Extract the release archive and copy the `user-sync` (or `user-sync.exe`) binary to the system's sync tool directory.
82+
3. Run the sync tool in test mode.
83+
1. Open command-line terminal
84+
2. `cd /path/to/ust`
85+
3. Run the command you would use to make a live sync, but running the UST executable and appending the `-t` command-line option
86+
87+
This is the command you would run from the cron job/scheduled task, or the associated shell script/batch file
88+
89+
**Linux example** -- if the command to run the tool in live mode is `python user-sync.pex --process-groups --users mapped`
90+
then the command to test the new binary version is `./user-sync --process-groups --users mapped -t`
91+
92+
**Windows example** -- using the pex-based command in the Linux example, the command to test the Windows EXE is
93+
`.\user-sync.exe --process-groups --users mapped -t`
94+
4. Compare log output from test run to log output from previous live run.
95+
96+
There isn't an exact procedure we can outline here -- each UST installation is different. In general, look at the counts in the
97+
sync summary and make sure they aren't radically different. Look at the log messages for any errors or anomalous behavior.
98+
99+
Note that log messages in the test run may be worded differently or may appear in a different order.
100+
101+
If you need help, please [reach out](#getting-help).
102+
103+
5. IF the test logs look good, update the sync command in the cron job/scheduled task or associated script.
104+
105+
Use the same command you used to test the file with the test mode flag (`-t`) removed.
106+
107+
Check the UST logs after the next time it runs to ensure it behaves as expected.
108+
109+
# Getting Help
110+
111+
Please [create an issue](https://github.com/adobe-apiplatform/user-sync.py/issues) if you need help with the upgrade process.
112+
113+
[Previous Section](update_cert.md) \| [Back to Contents](index.md)

0 commit comments

Comments
 (0)